When Documentation Goes Bad.

I’m going to paint you a picture, and when its over I want you to purge your memory.  Imagine being hired at a large company, given access to SharePoint, and then tasked to understand the Contract System.  You do a quick SharePoint search and VOILA!


You found the golden ticket, the requirements.  You open the highest version navigate past the corporate logo, table of contents, and make it to the Overview.


“This document outlines the system requirements for the Contract System.  The OSI 29 Implementation project requires that planet clients be updated manually in the production feed.”

Functional Requirements

CS-EN-001 Populate Clients from Contract System
CS-EN-001 1 Disable Access to non TMA Clients
CS-PR-002 Populate a unique identifier(ContractSystemID) for each record in the ContractSystem table.

System Requirements

CS-SR-001 The process shall only accept authenticated users.
CS-SR-002 The process shall log any attempt to gain access to secure systems.

You slowly start to skim read because nothing is making sense, and before you know it you are at the appendix which contains a Metadata section.

Name Comment
ContractSystemID Unique Identifier for the Contract System table
ContractName Name of the contract
ContractDate Date of the Contract
UpdatedDate Date Updated

You then close the document, having an even worse understanding of the contract system.  You turn back to a SharePoint search and uncover countless other useless documents.


Where do i start?

The most common sign of documents gone bad, is when you have to talk to people to understand a system and those conversations always end up getting lost.  Requirements, database structures, acronym filled process diagrams mean nothing to an outsider.   Start with something that gives a high level picture of what’s going on, in plain English describe what the system provides, who it interacts with, and  any dependencies.

The problem is companies use documents to keep people busy, check project plans boxes, and keep consultants on client sites longer.  The documents should be driving design, but obviously they are not.  If you take anything away from this blog let it be this:  Only keep 1 previous version of a document. If you find yourself working on v1.9 and have to go back to a v1.0 you have done something drastically wrong in your versioning process.

My second issue is polluting SharePoint with useless documents.  All SharePoint administrators should archive documents that aren’t accessed and send them straight the the recycling bin (just don’t empty it).

If you get tasked to write a document, you always should first identify your audience.  If you find that your audience doesn’t exist, or is yourself find another topic with a proper audience.

Instead of wasting time having a consultant write a support document, how about you force them to shadow an employee that is taking over developing or maintaining the system?  And then ask the Empoyee to write the support document, and then ask the Consultant to edit?

My last and final point… Requirements, they exist for good reason, and should always exist, but who says they have to be so vaguely worded and why are there so many!

I never thought i would say this, but the government does do this well, its called DODAF.  Google it, read about them they describe a document framework that works!

Tagged with:
Posted in C#, LinkedIn, Programming

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: