3 ms·
Ask HN: Should developers be writing technical documentation?
Not to be confused with the question: "Should developers document their code?". I have no problem with developers working on internal documentation. Should developers be writing external documentation for their code that customers will be using? This includes installation, terminology, how and when to use APIs, etc.
The company I work for has developers writing customer facing technical documentation and this has always felt off to me. Proper documentation takes a different level of skill, and I don't feel that writing the code automatically makes me qualified to correctly express how the code should be used. This often results on poor customer facing documentation.
I personally feel that technical documentation takes a different level of skill and developers should be focused on developing. Am I just griping too much? Do other companies do this?
- tjr 12y agoIn my experience, the main disadvantage to developers writing documentation is the potential for poor writing. The main disadvantage to a dedicated technical writer authoring documentation is inadequate understanding of the software, including what it does and why. Some developers enjoy writing, and would do well at writing documentation for their own software. I suspect at least most developers could be good writers if they practiced at it, but if writing is a task they are being forced to do against their will and desires, that will likely reflect in the writing. If nobody on the project enjoys writing and does it well, then it may be worth bringing in (at least part-time, or on a per-project basis) a dedicated technical writer. But at least one of the developers should be prepared to explain things to and answer questions of the technical writer.
- edoceo 12y agoWe have two stages. Devs write rough draft of tech doc, include examples. A writer takes that and makes it ready for public consumption. They will work as a pair to create final draft and organise that to our doc pages
- crimsonlotus 12y agoThats more or less how it works here. Our writer check for grammatical errors and the like, but the majority is written by the developers. I guess its more common than I thought. Thanks for your feedback.