Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I know it's a very subjective question , but this is one section of Software Engineering wherein I haven't seen any improvement in terms of how we can do it in a better way. I guess every programmer does documentation with some frustration, but when working I feel it's the most important tool for me. How can the process of creating and maintaining documentation be done in a better way?

share|improve this question
    
Better than what? This is difficult to answer without knowing what existing process you have in mind. –  Anna Lear Feb 16 '11 at 14:08
    
It's not the existing process, but my objective is that I whatever I do, someone joining after me should not rely on me for communication, my documentation should be enough for all his queries. –  gizgok Feb 16 '11 at 14:42

1 Answer 1

up vote 4 down vote accepted

There is no silver bullet. Like other aspects of programming, you need to decompose the problem and tackle one area at a time.

Here are some ideas that can (in my experience) be helpful:

Reduce the need for documentation

  • There are often better ways to communicate than through documents, eg. face-to-face
  • Identify which documents have little value and stop producing them
  • Well structured programs need less documentation
  • Use meaningful variable names etc to reduce the need to document
  • Use code comments wisely
  • Link to appropriate web articles rather than reproducing them in your documentation

Generate documentation

  • Class diagrams can often be generated from code and then annotated
  • E-R diagrams can be often be generated from a databases
  • Use tools like javadoc to document APIs

Choose the right tools

  • If you want documentation to be developed collaboratively, use something like a Wiki.
  • If you want documentation to be kept in step with source code, keep the documentation in source control.
  • Consider the benefits of an integrated bug-tracking / knowledge-base / source control solution
  • Pictures can speak a thousand words. Use diagramming tools etc.

Choose the right medium

  • Instead of writing everything down, consider using video or audio recordings (great for both requirements capture and end-user documents)
  • Archive emails about the project

Choose the right quality

  • Not all documents have to be polished. Sometimes, a rough sketch is enough as long as everyone can find it when it is needed.

Choose the right people

People should document according to the domain of their expertise. For example, users should write user documentation (after all, users best understand the business problems that the software solves, and will express their understanding of the software in business terms).

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.