[HN Gopher] Ask HN: How to Improve Documentation?
___________________________________________________________________
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?
Author : shreythecray
Score : 15 points
Date : 2022-06-15 18:19 UTC (4 hours ago)
| hnthrowaway0315 wrote:
| IMHO documentation should include basic scenario examples. It
| should also include all quirks that the team was forced to
| implement but difficult for other people to pinpoint.
| verdverm wrote:
| https://documentation.divio.com/ is a great framework for
| documentation
|
| 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
| warrenm wrote:
| What I wrote ~9y ago is still a pretty accurate representation of
| my view - https://antipaucity.com/2013/10/11/theres-never-enough-
| docum...
|
| #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
| throwaway81523 wrote:
| First of all you need an interalized conviction, based maybe on
| long and painful experience, that good docs are worth the trouble
| that it takes to write them. Second, your management has to back
| you up on this, when normally they are obsessed with slamming
| today's feature out the door and letting the underlying confusion
| keep piling up. And third, you have to put in the work of
| actually writing the docs. It's not the world's most challenging
| or demanding work, but it takes understanding of the topic you
| are writing about, and sustained effort to keep the words flowing
| into your keyboard.
|
| 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.
| warrenm wrote:
| Also see https://pm.stackexchange.com/a/802/167
| themodelplumber wrote:
| Good q! To me there should be a good ratio of "accuracy scent" to
| "usefulness scent".
|
| 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.
| armchairhacker wrote:
| I like API docs. Docs where each module, definition, function,
| etc. is documented. Then I can see the docs in my IDE.
|
| 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.
___________________________________________________________________
(page generated 2022-06-15 23:02 UTC)