3 ms·
Ask HN: How do I write good documentation?
I got a freelance job recently, that wants me to write documentation for a static site hosting platform, the thing is, I've never written or even edited a documentation before. how should I go about it? any tips?
- ss48 4y agohttps://diataxis.fr/ https://diataxis.fr/ gives some good guideline for classifying types of documentation .
- taubek 4y agoIf you have time go through Google course for technical writers. [1] Also Write the Docs has a great Guide [2] [1] https://developers.google.com/tech-writing https://developers.google.com/tech-writing [2] https://www.writethedocs.org/guide/ https://www.writethedocs.org/guide/
- hoot 4y agoGet ChatCPT to write it.
- warrenm 4y agoFirst, practice Second, read other's examples (eg MSDN, developerWorks, Docs.Splunk) Third, practice Fourth, get feedback (and incorporate all the constructive bits) Fifth, practice Sixth, focus on why more than how; leave out used to be in favor of this is now; be concise; crosslink other docs Seventh, make it maintainable - you do not want to "own" this forever and always...eventually you won't be there: make it something someone else can pick up and run with (and not have to recreate from scratch) ---------- Some resources I've written (and a Wikipedia page): - https://writing.stackexchange.com/a/33505/1317 https://writing.stackexchange.com/a/33505/1317 - https://writing.stackexchange.com/a/33578/1317 https://writing.stackexchange.com/a/33578/1317 - https://pm.stackexchange.com/q/799/167 https://pm.stackexchange.com/q/799/167 - https://en.wikipedia.org/wiki/DIKW_pyramid https://en.wikipedia.org/wiki/DIKW_pyramid - https://antipaucity.com/2013/10/11/theres-never-enough-documentation-theres-too-much-documentation/ https://antipaucity.com/2013/10/11/theres-never-enough-docum... - https://antipaucity.com/2013/02/10/organizational-knowledge-capture-retention-and-dissemination/ https://antipaucity.com/2013/02/10/organizational-knowledge-...