I was browsing the net to see if I could find a good summary on how to write good documentation.<p>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.<p>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.").<p>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.
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.