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
    
You say, "my documentation should be enough for all his queries". Why? I'm not saying you're wrong, just that examining your reasons for believing this may help you refine exactly what you want your documentation to achieve. –  Kramii Feb 23 at 16:54

1 Answer 1

up vote 6 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.
  • Use an interactive whiteboard in meetings and keep a copy of things written on the board (or if using a regular whiteboard, take a photo).

Choose the right medium

  • Instead of writing everything down, consider using video or audio recordings (great for both requirements capture and end-user documents) and photographs.
  • 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).

Build the right culture

Sometimes, documentation problems are really people problems:

  • If you feel that documentation is the best way to preserve knowledge in your company, the real issue may be one of staff retention.
  • If you feel the need to document every detail of who did what, the real issue may be that your organisation fosters a blame culture.
  • If you feel the need to document as a means to share knowledge, you may benefit from finding out why people don't just talk to each other.
  • If you're documenting every detail of every little decision, you may find find that you're working in a low trust environment.
share|improve this answer
    
"There are often better ways to communicate than through documents, eg. face-to-face" - those faces who were present will possess knowledge which ought to be documented. Others will not. And, when those faces leave the company, so does the knowledge. Documents stay around. –  Mawg Feb 23 at 16:00
    
"Link to appropriate web articles rather than reproducing them in your documentation" - S.O depreciates this, in case of link rot. Shouldn't you do the same? –  Mawg Feb 23 at 16:01
    
@Mawg: Both good points - you need to use your brain when applying these suggestions, not just follow them blindly! –  Kramii Feb 23 at 16:41
1  
Some other candidates for generation: Release Notes, Test reports, I've also in the past had automatic generation of screen shots for the user guide, which saved some time if a minor UI tweak happened but I'm not sure it was a net win overall given the effort to automate the screen shots in the first place –  jk. Feb 23 at 17:30

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.