from Hacker News

Ask HN: How to write good documentation as a team

by zwarag on 6/14/21, 9:05 AM with 1 comments

I was browsing the net to see if I could find a good summary on how to write good documentation.

In the team I work now (which works on an internal framework) there are 7 People working on features and everyone is writing some part of the docs and the difference in style is very noticeable.

Some like to write from the personal perspective (I), others in a teaching manner (we, you) [have,could,should]. Some write in an asking manner, other in a commanding manner. Then there is the debate between as concise as possible and "enjoyable to read" as possible ("Go to foo for more information." <-> "If you would like to read more about this topic, head over to the foo section.").

We have a Pull-Request guide that has some review points concerning documentation. But I feel like it's only partially effective. So I was wandering, how is HN approaching their documentation writing.

  • by gradschool on 6/14/21, 2:37 PM

    FWIW, I used to work as a technical writer. To treat this issue with the seriousness it deserves, I suggest hiring a copy editor with a technical background, either full time or on contract, with an initial brief to standardize a house style on which everyone can agree. Older people are a great source of potential hires because many of them went to school when grammar used to be taught. As an aside, I think you're doing the right thing by getting developers to document their own work even if their documents need rewriting by someone else, because doing so compels them to think clearly.