Documentation

I was once told.. bad documentation is like cold pizza. When you’re hungry… it’s better than nothing.

I’m a huge proponent of documentation for the following reasons.

  • You will be using your code weeks, months or years from now, having any documentation is great, and helps you or anyone else reading it to more quickly get up to speed on the project you were working on.
  • You want other developers to use your code, a well written set of documents will provide quicker understanding of your code and / or application.
  • You want other people (users or developers) to help you out in case an issue arises. The sooner they can understand what it is you were trying to do, the quicker they can assist you.
  • You want to design and write more efficient and usable code. Documenting it helps can help greatly in your understanding of a particular set of ideas or logic.

I’ve written many types of documentation, from Requirements, Architecture/Design, Technical, bug/fix, user and training. In most every project I’ve worked on, somewhere in the system, a folder can be found by others that outline from a high to granular level what it is I’ve done, what I’m currently doing and what I plan to do.

The really great thing about creating documentation while designing or working on projects is that if for some reason you get pulled off to work on something else, it shortens the time of getting back up to speed to where you may have left off.

I like to be involved (if possible) at the very beginning of a project build. Whether or not I’m designing it I can still make notes and ask questions as the development life cycle begins and these notes can help assist in creation of documentation.

As I’m working on a project I tend to make lots of screenshots of important data or steps to assist me in clarifying where I am in the process and design and to help me quickly determine if I’m getting off track. Many times I’ll take this document and present it to others to see if they see any potential issues.

There have been times that I need to step off of one project to handle a pressing issue or a higher priority project. Having usable and understandable documentation allows me two things.

  1. The ability when I return to the project to get back up to speed quickly.
  2. If I need to hand the project over to another developer they can find out where in the development of the project I left off and pick up and continue at that point so that development time is not greatly impacted.

Project Documentation can come in many forms:

  • Business Requirements
  • Project Business Case
  • Change Requests
  • Risk / Issues Logs
  • Project Schedule

I try and keep clear and concise documentation because it can stimulate and structure critical thinking, it provides memory containers for later reference and it helps in keeping team members and other stakeholders informed.

Examples