Get your project's documentation right the first time

It's important not to cut corners when it comes to project documentation, since documentation is critical to your project's success. You need to know how much documentation a given project needs to get it right the first time.

Both project and development managers love to deliver, be it cutting-edge software applications, network solutions, or simply enhancements of existing legacy applications. Their focus and passion is to design, build, test, and deploy IT solutions in the best possible manner. Sometimes, however, the importance of having project documentation in place for every project doesn’t always resonate with managers. In my work on many software development projects, I’ve sometimes questioned the feasibility of creating too much documentation. Superfluous documentation can slow down the entire project by requiring developers to create lengthy, repetitive specifications or test plans instead of spending their time on the actual project. But as a mentor once told me, “If it ain’t in black and white, then it really wasn’t said.”

Getting the message across
I recently bought a fly fishing rod at my local sports store and was immediately offered a comprehensive user guide on how to best use the rod, as well as other fly-fishing tips and techniques. It turned out that this excellent document was in reality a user guide created especially for this type of fly rod.

You can apply this example to any IT project. Each project is unique, and, therefore, requires unique documentation. The trick is to remember to add the appropriate documents once you’ve defined the methodology (i.e., SDLC, PMLC, RAD, XP, etc.) you’re going to use, and then decide which documents would really help drive the project through to a successful conclusion. For example, the concept phase would require a business case, feasibility study, and so on.

Architects, developers, DBAs, and engineers sometimes scoff at how “document-centric” managers can be. A common managerial refrain is, “We can’t proceed with the project until this document has been completed and approved by management.”

Let’s explore some of the reasons behind creating documentation for your project. Table A shows some of the pros and cons.
Table A
Advantages and disadvantages of having project documentation
Advantages Disadvantages
Facilitates team development Team member tasks will be ambiguous
Clarifies issues the project team may have Can be considered too administrative
Identifies what the project is and is not Slows down the entire process
Considered a pivotal communication medium Decline in standards
Prevents delays and rework Causes a rise in project cost due to delays
Allows for standarization of projects Poor quality
Provides traceability of what was said Considered by developers as non-value-adding

Minimum set of documentation
By this stage of the game, you’ll probably agree that it’s senseless to use each and every project document on your project. Be honest! You’ll be adding to your team’s administrative burden, and you’ll likely end up over-schedule because of it. For example, on a database migration project, it’s not efficient to use the entire arsenal of documents. Instead, you should selectively identify those critical documents—implementation plan, back-out plan, and so on—that are required by the business.

Both project and development managers need to realize that projects must be classified into groups in order to gauge how many documents each project needs. Here are some of the different types of projects you’ll typically encounter:
  • Small projects—These projects range anywhere from one to four months in duration. The emphasis is on speed and completing the project as quickly as possible. Examples of such projects are small migration projects, creating a Web site, or simply upgrading existing systems.
  • Medium-size projects—These projects take up to 12 months to complete, and they’re the norm for most companies. They are not that quick to resolve, and they usually involve external vendors and integration. The level of risk and change control increases with medium-size projects. Such a project might be developing a network center in a new location, or a business intelligence project.
  • Super-size projects—These are the largest projects. They may take a few years to complete. Examples of such projects are the development and deployment of a new billing system, a data warehousing project, or other lengthy efforts.

Determining the documentation needs for your project
So the question arises: Which minimum set of project documentation do you need? Remember that writing documentation takes time and money. Therefore, the size of the project has some bearing on the number of documents you’ll need. In addition, developing project documentation becomes even more crucial when working with federally regulated and validated systems like those used in the medical, pharmaceutical, or defense industries. An Australian CSIRO survey of some 351 companies found that a decline in documentation contributed towards a decline in project efficiency. In cases where hardly any documentation existed, projects had an average cost overrun of 11%.

Figure A shows these three categories of projects and the minimum set of documents that you’d need for each. For small projects, the emphasis is on the minimum requirements. Medium-size projects gradually require more documentation, while super-size projects require the most because they require a  great deal of communication and coordination.

Figure A

Accordingly, many corporations that utilize heavyweight methodologies like SDLC or PMLC as their project standard provide their project teams with a wide spectrum of documents to use in each phase of the project. Depending on how many phases are in the product lifecycle, you could end up with quite a few documents. In contrast, those companies using lightweight methodologies move more swiftly and rely on source code and modeling diagrams as their project documentation.

Creating the right documentation the first time
Sometimes project or development managers don’t want to recreate the proverbial wheel by creating brand-new documents for their projects. As an alternative, they can use a wide variety of tried-and-tested project templates. This gives the manager more time to concentrate on the actual project, rather than spending it on developing new documents from scratch. Whatever you prefer to call them—templates, artifacts, or boilerplate templates—they form the backbone of essential project documentation.

Whether you’re managing projects throughout the entire lifecycle or simply developing technical specifications, you’ll surely have to deal with details from various sources throughout the project—such as the client, users, and vendors—and at some point you’ll have to write something down.

Specifically, project documentation focuses on guiding the project team and readers to:
  • Define the aim and background of the project.
  • Identify key deliverables and dates.
  • Document the technical parameters and technologies to be used.
  • Address the manner in which items will be built or deployed.
  • Assess items such as quality, scope, resources, risk, training, and cost.
  • Document any back-out or contingencies that could occur.
  • Communicate progress and update stakeholders.

Go forth and document
Proper documentation is critical to your project’s success. Whether it’s in the form of source code, plain hardcopy documents, or transmitted in electronic form, you need to plan for and develop project documentation prior to starting the project. Managers should anticipate the time required for developing such documents and update them whenever a change occurs.

In future projects, I’m confident that PMOs and company executives will place a greater emphasis on enforcing the need to create and manage the “correct” set of project documents. To this end, we’ll see document management tools such as FielCM, RDT, eRoom, Adept, EDMS, TeamCenter, and CS-RCS playing a key role in managing project documents. Remember, information relevant to your project must be documented. As my mentor regularly told me, “Give it to me in writing, buster!”

Editor's Picks

Free Newsletters, In your Inbox