Ask HN: How to Improve Documentation?
What are some features or styles of documentation that make you want to read more vs. what are some characteristics that make you hate documentation?
There is not a stimulating code-test-debug cycle in writing like there is in programming. It's just work work work. There is no framework or tech stack that can change this. So you have to like writing, and think that it is worth it. You have to deal with that first. Worry about subtleties later.
If the API docs have a good search function, then I can actually search directly from the docs instead of Google. They should also have lots of links because often I’m just clicking through references.
I also really like examples. Especially when they’re examples of something i might actually do (e.g. how to use a file library to read a file), to the point where sometimes I just copy/paste them.
High-level theoretical documentation is good too, but make sure you have the API documentation and examples first. Also try to use graphics and diagrams where appropriate. People have garbage attention spans and most people won’t read a wall of text.
The best documentation I know so far is the Rust standard library in docs.rs. Lots of Cargo packages also have great documentation. The Rust / Cargo books are a great example of higher-level documentation. If you write docs like well-documented packages on docs.rs you should be good.
#Not Enough:
- why-tos (instead of how-tos)
- tutorials on things you need
- architecture explanation
- design philosophy “how we got here”
- “why we are here”
- future plans / roadmaps
- deltas from standards recording
- back-/cross-references to extant (even from other vendors / sources) documentation
#Too Much/Many:
- extraneous verbiage – use terse verbosity
- tutorials on things you don’t need / care about
- discussion of non-core aspects of the product
- how we used to do things
- assumption of comprehension
- plagiarism – ie, non-attribution of sources
- braggadocio (not just excited) tone
- different “voices” or styles
For internal documentation, the most memorable/painful instances I've encountered has been that the code is overly complex and I would have liked documentation to help me understand why we have so many parameters and configurations and their impact. I believe having more explicitly defined methods help reduce ambiguity within the code. I've seen many examples of methods or objects where the goal is avoid as much repeated code as possible which create these burdensome solutions, so it drives the responsibility on the clients and developers to understand how to configure the input to get the desired behavior. Often times, we don't need the multiple layers of abstraction or configuration just to consolidate everything into a method, I think it's fine to have multiple methods with explicit use cases. That helps developers read the code easier, understand what is happening, and is less mentally challenging. In my opinion, making the code easier to read will help reduce the need for extensive internal documentation besides the required onboarding, dev setup, and overall architecture designs.
We don't always go to the docs for the same reasons, you'll want content for each goal the user has.
Easy navigation and discovery, typically I have an issue or problem that I'm trying to resolve.
Don't Make Me Think is a good book for understanding how users read the internet (and documentation in this case), lots of good tips / practices
Documentation System, https://documentation.divio.com/
tutorials, how-to guides, technical reference and explanation
They each serve a different need during the phases of learning and using a system.
* Avoid traditional documentation unless you absolutely need it
* Write good, readable tests! For developer users, this is the most 'honest' documentation to read
* Make other types of documentation as testable as possible. On our project, we maintain a series of jupyter notebooks for documentation heavily sprinkled with asserts to prove the state of the world exists as expected...
* TIMESTAMP - Prefer writeups, articles, blog posts, etc with timestamps over 'documentation' that promises to be current - this way its known when the information was relevant, and it's expected things grow out of date (like picking up a 1 year old book on a technology). If someone finds it useful and wants to update it, they can update the timestamp. Otherwise, its still a useful bit of context for a given snapshot in the past
Some documentation is clearly written for subjective accuracy & coverage. The author really wants to nail down the full set of conditions or rules that applies to the given term, section, keyword, etc. Each sentence builds on the last. There will be no skimming here--you must be a sequence-consumer and maybe even some kind of logic-critic to really enjoy this.
That's nice unless you aren't wired for that kind of reading, or you've got other things to do, and you need a common answer or solution fast, and there's no FAQ or it's not in the FAQ. Someone told you to read the docs, and you start to realize that the docs are more of a schema than a how-to. Well, sometimes that really sucks.
But also sometimes there's not enough accurate coverage, and the docs simply say e.g. "this function draws a line" and even offer some examples. But none of the examples cover all the stuff that you can do with the function and there are clearly a number of additionally usable keywords or options up there, and if you look in the language source there are a bunch of single-letter vars all over the place with no comments.
So there's this gap between "here's how this part works & you're on your way" (casual) and "here's REALLY how it works" (orthodox) that is worth giving reasonably both-sided attention IMO if you want to strike a good balance for readers.
Some other factors: Is the documentation kept up to date, does it cover OS-integration factors (e.g. where is the config kept and how does it work), how does it read on mobile, how well does the web menu work, is there a URL segment per topic, is there a link from docs back to language home page (not just a self-contained doc blob), etc.
A bit of a tangent, but I do think some basic web sense can help if the docs will be published on the web. I recently worked with the maintainer of a wiki help manual for a programming language on this. It seems they had spent a LOT of time deciding which camel case words to use for their wiki, something like a decade ago.
And now the problem is, somebody has since taken the official docs to a different domain name, improved the SEO by demoting camel case in favor of fully descriptive page titles, let the docs go out of date, and now there are these obsolete docs with much better SEO that outrank the official up-to-date docs. And this third party can't be reached, so the creative solution is to do tons of SEO-style work on the current docs.
Which of course, SEO is the absolute favorite topic of every programmer, especially when someone else is showing them how much their SEO needs to improve :-) /s
Anyway! Good luck with your blog post or docs project.