Robert Corvus

Here are some thoughts about documentation, including guidelines and best practices on documentation of code, defects, and application usage.

Code Documentation

I’ve worked in a lot of different development teams at a lot of different companies and I can say that no one even tries to create hard rules around documentation of code for developers.  Mostly it’s because it’s so subjective, but also because it would be so hard to enforce.  However, a general guideline or “best practices” for code documentation would include:

1)  Use meaningful variable and property names (i.e. call a variable “agency”, not “a”;  call a property “DependentService” instead of “ds”, etc.)

2)  Use meaningful method or function names instead of code comments.

For example:

public void GetDependentServiceForXYZService()

instead of

// get dependent service for XYZ service
public void GetService()

3)  Don’t add pointless, redundant, or obvious code comments.

Example 1:  Don’t do this:

// get dependent service for XYZ service
public void GetDependentServiceForXYZService()

Example 2:  Don’t do this either:

// set agency to null
agency = null;

3) In general, only add code comments for anything that’s may seem out of the ordinary or that you yourself as the developer may cause you to get confused when you look at your own code 6 months from now.

Defect Documentation

Documentation for requirements and defects found in QA testing will need to be much more strictly enforced because there are certain things everyone (developers, testers, acceptance managers, etc) need to know to replicate, fix, and retest the issue.  Things that would need to be known for documenting a defect include:

1)  What screen was the error seen?

2)  Steps for reproducing the error

3)  What environment was the bug found?  (i.e. dev, qa, pre-prod, acceptance, production, etc)

4)  Date it was found

5)  Version of the code it was found in

6)  Who the bug is assigned to for fixing, who should it be assigned to for re-testing, etc.

7)  Screenshots of the error would be nice

All of these can be easily enforced with a bug tracking tool like Remedy, TFS, etc.

User Documentation

Documentation for using the application is a different ball game.  There are definitely no rules here, every company and every app had different requirements for user manuals.  Usually acceptance managers/testers, business analysts, and QA testers are (a lot) better than developers at documenting how the app is actually used by the business.  Usually help links/popups are best for documenting an app because no one reads the manual.  If you have a really complex app, you may need to hire a tech writer/trainer to document everything for you.  Short videos of how to use features or complete tasks with the app are awesome (they’re also much appreciated when learning linear algebra www.khanacademy.org).