Ask HN: What is key to good technical documentation?
I’m going to relate an experience rather than answer your question. I don’t think the question is in its best form because it can be time consuming to write proper documentation. The existence of the “fairy godmother” takes time out of the equation which is an important variable.<p>I used to work at Microsoft on a team with poor documentation. By my reckoning developers writing code would have preferred better documentation while developer managers couldn’t justify the time to write it. Both preferences were sensible.<p>From the implementer perspective you could get caught up on a problem for several hours before having a conversation with another developer who could unblock you instantly. If the content of that conversation had existed in some document it could have been searched and several hours could have been saved.<p>From the managers perspective, product requirements and features changed so rapidly that a few days spent writing documentation could easily create a document that no one would use. Indeed, this was the case in a few experiments.<p>I lead a team for awhile and we hit the first problem a lot. However, I noticed that most of the conversations which unblocked my team had happened over email (I was CC’d). The tone of emails did not make for perfect documentation but they were helping my team so they were better than nothing. I decided to start taking some of the emails and pasting them into a OneNote document. After a few months the result was a large collection of imperfect documentation created very economically.<p>The OneNote document was wildly successful:<p>* Because the notes were from emails which had at least unblocked one member of my team, they had proven value.<p>* Because developers were already writing emails there was low cost to pasting them in OneNote.<p>* Developers could also correct the OneNotes and everyone would get the changes unlike an email thread which was only accessible to people on the to and cc field.<p>I also believe that the imperfections and limited editing features of email made it easier for people to write these documents: they didn’t feel like the documents needed to be well-formatted or perfectly written, if someone had something to say they had unlimited license to paste it in the document.<p>So thats been my experience and I will bet on it again in the future. The only caveat is that I worked on games which is the cause of the rapidly changing requirements. “Unfun” features could entirely be cut and we essentially rebuilt the product every few years to release a new game obsoleting much of the documentation. This sort of thing may not work for a public facing API for example.