🤓 Documentation 📕

Hey! Thanks for reading! Just a reminder that I wrote this some years ago, and may have much more complicated feelings about this topic than I did when I wrote it. Happy to elaborate, feel free to reach out to me! 😄

🎵 The song for this post is Street Life, by Randy Crawford. 🎵

It was the lack of available docs that prevented me from running COBOL ON COGS

These blog posts can just be called "Pablo reads and appreciates Hillel Wayne," who published another piece I loved on documentation in Markdown. Namely, if you're writing code docs, consider using something other than Markdown. Hillel wrote this on his mailing list and not his blog, but for the second time it was posted to an aggregator, which doesn't seem to be his target audience for these writings, where the most common criticism is "well, a lot of people wouldn't write it in anything but Markdown. Would you rather it didn't exist at all?"

Which… I guess? Maybe? Obviously user experience and friction matters, but often when people say "worse is better" reflexively, I hear it as the "good things aren't possible" of programming culture. IMO, to fixate on that is to miss a lot of good material.

Here are some thoughts about documentation that this got me thinking:

Docs are great canary for issues in programming culture because they're very low-tech, while so not a solved problem. In fact, I don't think we can agree on good solutions to the problem are! Hillel's criticisms seem to be looking at functionality of the documentation: can you view it offline? Is it easily readable, searchable, and can you reconfigure it to your tastes? For every post on "how to supercharge your Vim," how many have you read from people who take reading and using docs seriously? How about making them? Do you know Javadoc conventions? Ocamldoc conventions? Have you run into limitations generating them before? Does it make sense to make them language-specific, or would it make sense to do something like the Language Server protocol for them?

For a while I tried Dash, an offline-enabled documentation viewer and snippet manager. It seems great! I downloaded some docs and learned a lot of Clojure on a train once. I stopped mostly because I didn't let the habit stick, but was stopping really a great move? How many times have I had to lookup Python's mock library with the Google intermediary lol.

How does documentation (consuming or generating) play well with your tools? I often think about Gary Bernhardt's text editor in A Whole New World with features like "integrates with Sentry/Rollbar to jump to unresolved exceptions" or "integrates with Stash or Splunk to where errors were logged." What tools would and could we build if we really used documentation. How could we quicken the turnaround when you need to look something up?

Additionally, how can we make them more collaborative? Bryan O'Sullivan wrote two great books in the early parts of the last decade, on Haskell and Mercurial. If you click into any chapter, you'll see expandable comments under each paragraph—while writing, people left feedback he could incorporate into subsequent revisions. How can we make updating docs painless?

A hot take: devs don't read documentation almost ever. This isn't to blame them: docs aren't always great, understanding anything interesting is hard, and you can often get results without deep reading or thought. This is a bit in line with the transition from "understand the program and all its components well" to "poke it until it does what you need" which transitioned MIT from SICP in Scheme to their new curriculum in Python. What are the causes and consequences of this? What happens when we change variables on how easy or hard it is to read or produce docs?

Examples in documentation say 1000 words, what more can we do here? Elixir will run tests in your docs to ensure that your docs don't lie. I can't find the link, but there are projects that search open source code for uses of a library in the wild and collect them, so you can see it used in real projects.

idk man, there's so much here!! Why do we have jobs?! Let's just noodle on this and related problems! throws papers into the air