Why Application Documentation is so Important

Any application written, no matter how large or small needs documentation.  It doesn’t have to be fancy but the documentation must be written and it must be kept up to date – no exceptions.  The documentation can be as simple as a one page document that spells out to anyone who supports the application the following things:

  1. What the application does, how it works
  2. Who uses the application
  3. Where the application lives (server names/passwords)
  4. Databases it relies on (server names/passwords)

If this information is not documented (and the documentation not kept up to date), then troubleshooting the application may take hours which means the users are left waiting for (sometimes critical) applications to be fixed.

This is a typical scenario of what can happen when documentation is not updated (it happened to me yesterday):

We have a vendor written application that resides on two servers and it has several passwords and databases.  Years ago when I was a part of setting up this application, I documented everything about it.  I wrote a short one page document of all the critical stuff: how it worked, its databases, passwords, and server names.  Then, a few months ago, another team member upgraded this application and put the application and its databases on new servers.  Did this employee document any of this? No. Is this employee still with our company so I can ask him anything about this application? No.  Are we in a bind because of this? Yes.  Do you know why? Because the application went down yesterday.  We looked at the documentation I had written about the application and discovered it had not been updated so we didn’t know any of the new passwords for getting into the administrative side of the application; we actually had to hunt and peck through the registry to find this information.  Troubleshooting this application yesterday was a complete nightmare and it took several unnecessary hours.  If the documentation had been properly updated, it would have saved us hours of frustrating work.  The fix was something so simple (a particular executable had to be running 24/7 before the application would work and this executable had stopped due to the server getting hosed due to the a/c going out in the server room) but since no one had documented this new process, we had to figure it on the fly which kept our users waiting.

Many IT employees will complain that they do not have time to write documentation or update documentation.  The only reason they do not have time is because they either don’t make it a priority or the clients don’t understand the importance of the documentation.  IT has the power to address both of these issues head on by making documentation a priority and letting clients know that if they want fast service in a stable application environment, then documentation needs to be considered as important as the application itself.

Example of a list of Requirements for a Simple Application

This web page is an example of a simple application (it is a web form): http://mummey.com/contactus.aspx. This form allows a visitor to enter his or her email address, a message and click on a submit button. When the user submits the required data, the data is sent in email form to a general mail box at mummey.com. An application of this size and complexity will take a programmer about 15 minutes to write. A full hour if you throw in testing, handing off to the client for user testing, writing proper documentation and publishing to production. However, this estimate could go up to several hours if you wanted the programmer to create artwork.

If you wanted a simple application like the one listed above, your requirements to a programmer would translate to something like this:

  1. One form that displays 6 items (welcome verbiage, navigation of some kind, graphics, form fields of email address and comments and a submit button).  We will provide the images and descriptions of the items to the programmer.
  2. The visitor to the form should be able to enter their email address, a message and then submit the message via a submit button.
  3. When the visitor submits the form by clicking on a submit button, the visitor email address and the message the user entered will be submitted as an email to this email address: xxxxx@xxxxx.com.

I need a programmer to write an application for me, where do I start?

Before finding a programmer, understand the basic application life cycle.  It is something like this:

  • Client comes up with a list of requirements (be as specific as possible).
  • Programmer is given requirements to study
  • Programmer gives estimate of time and cost of job based on requirements given
  • Programmer builds application
  • Client tests application and the programmer fixes any bugs in the application – this step loops until user agrees product is good. DANGER – it is in this step that scope creep can show its expensive head.  Scope creep is when a client at this point adds more requirements to the application, this is very easy to do because the client is excited about the project and the programmer is excited about the work and making the client happy.  If more requirements are thrown into the project at this point, the client needs to understand that the original estimate of cost and time no longer apply.  It is best to meet with programmer with a new set of requirements so the programmer can establish a new estimate of cost and time and if this new estimate exceeds the timeline of the client, then the application needs to be pushed to production as is with the original requirements and a new timeline/cost should be established for Phase II (new set of requirements) of the application with the programmer.
  • Programmer publishes the application to production.
  • Programmer delivers documentation in electronic form the client. Two forms of documentation are delivered: a user guide and a tech guide.  The user guide is a detailed step by step document of how a person would actually use the application (covering all of its features).  The tech guide is a detailed document containing the actual code of the application (or a link to where the actual code can be found), any passwords required of the application, detailed information regarding the database (if the application uses a database) and the language the application is written in.  The tech guide is to be given to any future programmers who may have to work on the application after the original programmer has won the lottery and moved to California:)
  • Client pays programmer.

Blog at WordPress.com.

Up ↑