Writing better documentation

I am currently in the AIM IT Leadership Academy. As part of this program, one my goals is to centralize and better manage training material and project documentation for all the teams at Phoenix Web Group. 


  • It’s easier for people to join a project if it follows standards.
  • Setup instructions for checking out a project are often missing and only known by the project members.
  • While end user documentation may exist, there is often times little documentation of how the code actually works. In theory code should be self documenting but in practice it’s always better to understand the rationale for decisions.

Where should it go?

In a /docs folder in the repository. I’m using Markdown Pad for all my documentation. I want documentation to live in the same repository as the code so we can track revisions and see what the code looked like when the documentation was written.

What should it include?

  • Project objectives including what the business value of each component is.
  • Contact information for the client including a summary of each person’s involvement.
  • Setup instructions. What dependencies need to be downloaded? Any drivers?
  • Locations of backups of test data for databases.
  • Core architecture components. Bonus points for an up-to-date architecture diagram.
  • Explanation of any critical algorithms.
  • Testing plan that should be reviewed with each deployment.
  • List common errors that might occur and how to resolve them.

When will it get updated?

This is the hardest part of documentation! Set up a recurring event on your calendar. Part of each iteration retrospective should include reviewing the documentation for accuracy.