Doin' Documentation - A Practical Outline

The Case For Documentation —

"...the pain, the pain", Dr. Smith — Lost In Space

"Documentation, schmocumentation, why should I do that? No one ever reads it, it takes too much time, and besides that I really don’t know what to document, much less how to. It’s such a pain…"

Everybody is polarized on the subject of documentation. They either love it, or hate it. Regardless of those feelings though, everybody who puts code to file should also perform a fair share of documentation. Why, you ask? Let me ask you some questions...

Have you ever had to inherit someone else’s project and couldn’t decipher why they did what they did? Have you ever written a snippet of code that you could return to six months or a year later and know exactly what you did and why you did it? Ever obtained code from another source but couldn’t make heads or tails of the included instructions? Ever reuse a block of code over and over again?

If any of those questions caused you any discomfort then you know what it is like to be without documentation. You’ll be the first to scream about the lack of documentation, no matter what your habits are on the subject. Let’s go step-by-step and see if we can remove some of the pain.

Start With An Outline

"It’s all very basic…" Sigmund Freud

It all starts with an outline. Even this article started with an outline.

Basic documentation should have the following sections (you can even create a template where you can begin to "fill-in-the-blanks" for each project).

• Description
• Definitions
• Scope Of Work
• Workflow Models
• Back-End Information
• Code Commenting
• Testing Procedures
• Project Tracking / Milestone List
• Sources of Resources
• Supporting Documentation
• Project Team & Responsibilities
• Sign-Off List

Where Do We Start?

"You say tomahto, I say tomayto…" George & Ira Gershwin

Documentation should start from the first moment the project is first uttered. Take notes. Lots of them. Ask the person requesting the project to clarify things that you do not understand. Make sure that ideas are communicated and understood clearly. In his book, Debugging JAVA, Will David Mitchell basically suggests writing the documentation before writing the first line of code. He also suggests writing the user’s manual before coding. This not only defines what the application will do, but exactly how it will do it.

Description

This is a description of what the project is and what output should be expected. (i.e. The RDCMS is a system designed to help manage web site content by defining a logical workflow for documents submitted to the system from author to approval.) Of course this description may be much longer depending on the project at hand.

Definitions

Define all terms that may not have an immediately recognizable meaning in the context of this project. To you, an author may be a book writer; to me an author may be the lowest level of access in a content management system.

Scope of Work

This should be the initial outline of everything that it will take to accomplish the core of this particular project.

Example;

• Prepare a database to serve as a back-end for containing information about representatives and regional contacts
• Prepare a set of web interfaces that will allow an administrator to add, delete, edit, or otherwise maintain information about representatives.
• Address information
• Region served (i.e. multiple states or countries)
• Contact information (multiple per company)
• Prepare a system of help files that can be accessed from the various interfaces
• Provide multiple methods of print-out including a ‘print-all’ method that will format the data in such a way as to be useful in printed form.
• Prepare a lesson plan to train users and administrators on system usage.

Workflow Models

A workflow model is a document designed to show the process of workflow visually, including high-level decision structures. These are also known as flow-charts. Each process can be broken down into basic pieces.

Example;

• Input for this process
• Decision to be made (true or false, yes or no, equal to this or that, etc.)
• Output for this process

These visualizations will help to identify processes and problems that may be encountered with those processes. Draw as many of these diagrams as is necessary to illustrate the application properly. If you have an application requiring many processes you can tie these together by using a high-level workflow diagram.

Also in the workflow models can be visual representations of hierarchical information that effects the way your models would go together, for instance where a login scheme requiring various levels of security is required. Tying people to levels can be made easier due to the ability to visualize the levels.

Back-End Information

Here is where you state the tools / technologies to be used for the project. This is where the development team gets their basic information;

Example;

• Server Operating System; MS WinNT 4.0
• Web Server: MS IIS 4.0
• Database System (RDMS); SQL Server 7.0
• Scripting Language(s); VBScript 2.0, ASP 2.0, ECMAScript 290
• W3C Mark-Up Language; HTML 4.01
• Etc., Etc.

Additional items that can be included with Back-End information;

• Location of files related to the project.
• Project Specific Usernames / Passwords (i.e. for data source names, etc.)
• Database Naming Conventions
• Database Table Diagrams (incl. data types, data sizes, key columns, etc.)
• Database Join Diagrams
• Global Variables (including how unaccounted for variables are to be specified, what kind of notation should be used, capitalization requirements, etc.)
• Special Programming Procedures
• Version Identification Document (Necessary if this project is an application.)
• Additional Technical Documentation
• Style Guide

As you can see the back-end information for a project can become quite extensive, but for every piece of information supplied here the project becomes more manageable. This section also highlights the fact that there are multiple levels of documentation, client level, technical level, and as you will see, user level documentation. Many of these levels overlap in the documentation process.

Code Commenting

Comments within code should be crystal clear and used only when needed to explain a process that may not be clear to others (or yourself at a later date).

Example;

Don’t — Dim strFirstName as String ‘string for the first name of the client
Do — funHeatLoss (complicated math here) ‘explain the function clearly

Commenting should be used primarily with procedural or scripting code. What about web site code, where most tags are self-explanatory? How about Cascading Style Sheets? Comment code there too, where it makes sense to do so. Special sections of a page should be delineated with comments (like News, NavLinks, etc). If you write a complicated nest of tables or some other form of complicated layout, comment that. Style sheets can contain processing information, color information, and other style considerations. You may want to refer to an established Style Guide, which is yet another piece of documentation that can be included in Back-End information.

If an excessive amount of commenting is required about a section of the code it should be noted in the Special Programming Procedures in the Back-End information. Included should be the code itself, an explanation of the procedure, where it is located (line number, module, page, etc.), variables passed to it, any other procedures that call upon this particular block of code, and anything else that would help to make the procedure clear. Then reference that document in the code comment, i.e. /*see SPP, section 1*/.

Testing Procedures (w/ Reporting Procedures & Problem Resolution)

Describe the various methods of testing (user testing, automated test procedures, etc.) that will be accomplished including how to report problems and where problem resolution information can be obtained. Document each problem in a central location, along with resolution information, so that the development team has access to information that may help them to resolve additional problems. If this is an application it is especially important to include a Version Identification document so that communications between testing personnel and developers will be very clear as to the version/build of the application tested.

Testing procedures can often be derived from initial user’s manual writing or the writing of a tutorial on the project or specific portion of a project. If you adhered to Mitchell’s advice earlier this documentation would be available to you during the testing phase.

The test phase can also help you to identify further documentation for interactive help mechanisms, the user’s manual, tutorials, and the like.

Project Tracking / Milestone List

Define a set of objects within the project that have verifiable completion rules attached to them. Once verified complete you can date and initial each milestone (perhaps with additional sign-off by the project manager or client). This will help you to maintain a good sense of the progress of the project, it will give you short-term goals, and it will provide a method to prove completion of certain tasks (especially useful if you are billing the client by progress completed or if you report to a manager that needs some form of measurable result).

Example;

Sources of Resources

What are the resources to be used for this project and where do those resources come from. Resources can be defined as anything from persons who specialize in graphics, data entry persons, web sites, library cd’s, code references, and everything in between.

Supporting Documentation

This section should contain either the supporting documentation itself or a pointer to where it would be kept. For instance, it would be impractical to include the HTML 4.01 specification, but a reference to its location would be pertinent.

Also include here references to articles that support certain methods within the project, project concept books/periodicals/transcriptions, etc.

Contracts (client to developer, developer to sub-contractor) should also be included where applicable.

Project Team & Responsibilities

Identify each team member (where there is a team) and the responsibilities of that team member. Provide contact information for them so that they are easily locatable for the duration of the project. If possible, especially where this is a mission-critical application maintain this contact list for as long as possible.

Sign-Off List

Finally there should be a sign-off list where the client and the developer (or project manager) sign-off on what are determined to be critical phases of the project. For instance, the Project Tracking / Milestone List provides very specific sign-offs for the developer(s) under Web Interfaces (see above example), but you would want the client to sign-off upon completion of all of the interfaces as a group. The sign-off list provides a certain "comfort" level to both the development team and the client as progress is demonstrated and accepted.

For Now —

"A conclusion is the place where you got tired of thinking." Martin H. Fischer

It seems to be quite a bit of work, doesn’t it? But you wouldn’t build a house without blueprints (or drawings at the very least), so why would you design an application or web site without forethought or planning? Develop a template for your documentation where you can go through and "fill-in-the-blanks." Even if the project is small and does not require each of the sections mentioned, practice documentation. Projects will go much more smoothly and clients, subcontractors, co-developers, and users will appreciate the product much more.