

Ask HN: Should developers be writing technical documentation? - crimsonlotus

Not to be confused with the question: &quot;Should developers document their code?&quot;. 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.<p>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&#x27;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.<p>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
In 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
We 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
Thats 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.

