Ask HN: What is the one thing you would change about documentation? | Hacker News Reader

Ask HN: What is the one thing you would change about documentation?

2 pointsazan-n5 comments

I've been in talks with research orgs, government orgs, and software companies and everyone seems to have something they would like to change about the way their documentation works.

I'd love to hear what HN has to add to that.

View on HN

More examples, illustrate the range of options and document all special cases. Think from perspective of "what context is this used from?" instead of just listing possibilities. Try to document what is going behind the scenes as much as possible, with minimal local jargon. Making stuff accessible to wider audience for debugging/auditing requires explaining design decisions at high-level(interface) and low-level(what is actually used). Otherwise users will start treating it as black-box binary blobs of mystery "code" that works by magic, because people just don't read source code.

Fewer emojis, preferably zero. They don't help with readability. No need to get cutesy with the "made with love" phrases either.

Documentation should be a simple boring set of pages, it's not a place for designers to practice new designs, frameworks, or navigation techniques.

Screenshots should focus on the content, not what it looks like on a specific device or window decorations. Screenshots are hard work though because they need to be kept up to date.

Please share some of the feedback you received from your other teams

Two things -

1) Keep it current, with a way of (actively) marking supercede / outdated / retracted copies (somehow? perhaps an (optional) url on each doc to check for "freshness"?))

2) Document the documentation. Having a master index greatly assists version control, esp for tech docs.

U/X. If your UX guy isn't giving you advice on your layouts, indices, density etc etc, your documentation will suck, and your maintainers will blame the user for not finding what they're looking for.

I would like to sort it by how common this issue is, so I don't look for the top of documention for edge cases or very old/rare issues.

Reply on news.ycombinator.com