The Artima Developer Community
Sponsored Link

Weblogs Forum
What is Documentation? Can we expect s/w engineers 2 be good at all facets?

15 replies on 2 pages. Most recent reply: Jul 7, 2005 10:05 PM by Kevin Hall

Welcome Guest
  Sign In

Go back to the topic listing  Back to Topic List Click to reply to this topic  Reply to this Topic Click to search messages in this forum  Search Forum Click for a threaded view of the topic  Threaded View   
Previous Topic   Next Topic
Flat View: This topic has 15 replies on 2 pages [ « | 1 2 ]
Kevin Hall

Posts: 1
Nickname: zmeson
Registered: Jul, 2005

Re: What is Documentation? Can we expect s/w engineers 2 be good at all fac Posted: Jul 7, 2005 10:05 PM
Reply to this message Reply
Advertisement
> 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 [ « | 1  2 ]
Topic: Any Idiot. Previous Topic   Next Topic Topic: Biscuit : A Parser Framework Based on YARD

Sponsored Links



Google
  Web Artima.com   

Copyright © 1996-2019 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use