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.”
|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.|
|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.
|ContractSystemID||Unique Identifier for the Contract System table|
|ContractName||Name of the contract|
|ContractDate||Date of the Contract|
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!