News for hackers. Stuff that matters.
Re:Ask HN: How to Improve Documentation? by warrenm on Wednesday June 15, 2022 @04:04PM (#31758700)
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

There are no comments on this comment yet.