> If we regard documentation as a form of recorded > communication, then so long as developers are able to > communicate to somebody who can document, then > there is no need for every developer to be proficient in > all facets of documentation.
I agree whole-heartedly with this. I actually do a LOT of documentation for my company, but do not publish the documentation. We have a technical writer who does that. But here's the key, he asks us about anything that is not obvious or clear to him. He tries as hard as possible to bring all the concepts closer to the ground so a larger audience can understand the documentation. Here's a few other keys things we have going on:
* Our tech writer has learned all the tools he needs to detect changes to the libraries. * He then notifies (and keeps on top of) our developers asking them for documentation. * Developers must provide (a) reference documentation (like Doxygen) (b) Short example code for smaller changes / concepts (c) Sample program for for larger changes (d) Concept introduction for new modules * Our techincal support team reviews the sample code to make sure customers will be able to follow and use it. Also, optionally our technical support team will review the reference documentation and concept introductions. * The tech writer then reviews everything, asking questions to make sure everything is clear. * In between major software releases (when the documentation gets updated), our tech writer tries to find ways to communicate difficult-to-understand topics via other media: flash annimations / video tutorials / quick-start guides. He will seek help from developers and technical support people when needed.
To make life easier for the developers, they are encouraged to write their module proposals in the forms of new reference material and sample code. Not only does this make the review process easier, but it makes the documentation process easier to finish in the mind of the developers.
We've been doing this for about 2 1/2 years now, and our documentation has improved drastically over that time. (Our previous documentation used to comprise of sample programs that had 1 function -- a 200 line long main() -- and reference material that looked almost like header files with a couple comments here and there.)
In summary, not everyone has to be good at documentation. Two things are needed: (a) someone to review docs who can effectively communicate to customers (b) a process that encourages developers to help produce the first draft of documentation.
Flat View: This topic has 15 replies
on 2 pages
[
«
|
12
]
Previous Topic
