A Better Way to Document Project-Related Information

Most federal agencies have formal Software Development Life Cycle Management frameworks for managing their IT projects. The names of the SDLC phases may vary, but most have one thing in common: the need to create and maintain documentation. Agencies often provide templates in Word, Excel or PowerPoint format to ease the process and encourage consistency across projects. Nevertheless, creating and updating these documents consumes much time and effort and yet often results in outdated information.

This article suggests a way to automate many documentation-related tasks to avoid redundancy and out-of-date information and improve the efficiency of the process.

Some of the most common issues with creating and maintaining documents for IT projects stem from their static nature and include difficulty working with template files, poor version control and duplication of information across documents.

Customizing document templates can be challenging. Finding where to enter information specific to a particular project is time consuming, as is finding that information if you are a consumer of the document. Formatting problems can be especially vexing, as the formatting does not add much value. Boilerplate text can be distracting and unnecessary and makes it hard to locate needed information.

Document owners often struggle with version control. Version control tools can help, but the practice of emailing copies of documents with filenames ending in “Final” or “Current” back and forth between co-authors is still common. This often leads to a situation in which no one is sure which version of a document is the most current and can result in different versions with conflicting information being in use.

Problems with duplication of information across documents leads to update anomalies. When presented with updated information, document owners must be sure to update all documents that contain it. If not, then the documents will contain inconsistent information and cause confusion for document consumers as to which version is the most current. Information often becomes stale.

For example, there are numerous project documents which contain a list of system hardware and software components, including design documents, architecture documents, system security plans, implementation plans, installation guides, and contingency plans. Some of these documents can more pertinent to consumers than the others depending on the current SDLC phase.

A design document has more relevance during the design and development phases than during operations and maintenance, and a contingency plan is more important during O&M. This often results in some of the documents being updated with the latest component lists but not others. Other types of information that are often duplicated include system descriptions, business process descriptions, solution requirements, architectural diagrams, project cost data, and contact information for project stakeholders.

A More Efficient Accurate Way

If most of the problems with project documentation stem from the static nature of documents, then the solution should consider ways to make them more dynamic. An ideal alternative to the traditional spreadsheets and word processing documents would be a dynamic shared portal that contains or links to all the project related data and information that is typically fed into the documents. It would have one master copy of each piece of data, eliminating update anomalies and simplifying version control. Guidance information traditionally used as boilerplate text would be segregated into more static guidance documents, help pages or Wiki resources at the organizational level and made available to all the project level portals. Varying levels of access would be granted to information consumers based on need to know, leading to better security.

If traditional documents are still required, the portals would provide the functionality to generate files using document templates and the latest project data and automatically add an “As of Date” and correctly incremented version number. The portals could also provide approval workflows for information updates and allow stakeholders to be automatically notified when changes are implemented.

The primary sources of some types of information would normally reside outside of the project portal, and in these cases the project team should work with personnel who own such information to get access to it.

For example, a list of hardware components would likely include the servers used by the system in various environments including development, testing and production. Information describing these servers would be dynamic, especially if the servers are virtual, and the most current data would be possessed by the operations personnel who manage the servers.

Ideally, information needed for the hardware list would be provided by running a script. In this case, organizations that use a DevOps approach to managing IT projects should have an advantage in that the project team is already working closely with operations personnel or providing their own operational support.

The ideal solution might require significant collaboration and development effort up front and take time to implement. If an organization isn’t ready for this, these are some best practices  most can implement in the short term to reduce some of the burdens of documentation:

  • Move boilerplate into separate guidance documents or web pages, so consumers who already know the background information can focus on the current project data that they need.
  • Link to live data whenever possible, or maintain only one master copy of data in a shared location for the project if not.
  • Create a centralized location for each project to store documents and data. This could be a web-based portal, but it could also be a database driven application or a version control repository, or at the very least a shared folder on a file server.
  • Use tables to present dynamic structured data. If they can be automatically updated using scripts, even better.
  • Use questionnaire style forms to capture unstructured data such as descriptions of business needs or systems. Then store the the captured information in a centralized location.
  • Use version control tools such as those provided by Microsoft SharePoint for documents and data.
  • Don’t email documents around to different authors. Instead, send links to co-authors. Use collaboration tools that allow real-time co-authoring if possible (e.g., Microsoft Office Online, SharePoint and Google Docs)

Keep The Objective In Mind

Organizations should keep in mind the purpose of project documentation is to convey information to stakeholders so they can fulfill their roles in creating an IT solution. They should not get locked into static forms of sharing that information that are difficult to maintain. If someone needs a list of hardware requirements, they should be able to get the list from a single authoritative source, not a word processing file with a table buried in it that may or may not be correct and up to date.

If that same person needs guidance on how to use that list of information, that guidance should be readily available, but does not need to be part of the list itself. In general, organizations should provide links to the original sources of information, which could be stored in databases, collaboration portals or available from web services. If it is necessary to create a document for compliance purposes, then it should be generated using these same sources of information, avoiding manual creation as much as possible.