TLDR; or, The Importance of Documentation

Why do we document? To put it simply, and paraphrasing Professor Henry Jones (father of the great archaeologist Indiana Jones):

“I wrote things down so that I wouldn’t have to remember.”

Nobody can be expected to recall the events that occurred in a meeting six months prior to release of a project. We document so that everybody understands the scope of work in such sufficient detail as to produce outstanding work.

Obviously nobody intends a project to go wrong, however, many stars must align in order to deliver a successful project, and not all of these can be anticipated. What we can anticipate is that thorough documentation will aid us positively in achieving the best possible outcome.

What constitutes "good documentation"?

In summary, good documentation consists of something that you can wholeheartedly rely on to inform a new employee at the company in;

• What you set out to do
• What you ended up doing
• Why you did it the way you did
• What problems you faced along the way and how you resolved them

Your documentation should be of such significant quality as to be completely reliable. Assume that everything you write for a project is going to be read by the customer, your manager, his or her manager, the managing director, your company’s solicitors, the customer’s company’s solicitors, the judge and your own mother.

The most important audience for documentation is: yourself. Read back what you have documented and ask yourself – will this make sense to me in six-months time? In six-years time? If it does not then do as all good programmers do; refactor and rewrite until it does.

What to document

Good documentation starts as soon as you shake your customer’s hand. A good tool for tracking every communication for a customer/project relationship is Atlassian Confluence. We always start with the following templates:

Level	Purpose
Customer Name	Name of customer, including customer code. Contact information should also be kept up to date, including availability of stakeholders.
Project Name	Title of the website or application; this too has a code, usually an iteration on the customer code.
Environments & Accounts	Repository of environment and access details (but not passwords) to all first and third party stores.
Meeting Notes	Dated meeting notes as they are taken during any face-to-face or teleconference call.
Roles and Responsibilities	Team members responsible for ensuring delivery of the project – both internal staff members and customer, as well as any third party contacts.
Specifications	All functional and non-technical requirements documents as attachments. This can and should also include Jira Stories for the project. Links to any previously completed project for the same customer can also be referenced.
Technical	All technical requirements documents and findings gathered before, during and after project completion. An overview of the architecture with notes regarding tech stack and areas of any complexity.
Repositories	Whilst storing everything in Confluence is recommended, some large assets may need to be stored locally. Note down the location on any network drives where assets can be found.

Project requirement gathering

Requirements vary per project size, complexity and how contact was made. Typically, a project will include:

• A written brief from the customer
• High-level request for proposal (RFP) document response to the provided brief
• Workshop scope document(s)
• Project scope document(s)
• Technical specifications document(s)
• Repository of all known third-party documentation required for the build
• Visual design and front-end development
• Back-end development
• Any content and/or data migration
• All functional requirements gathered
• List of acknowledged but out-of-scope items
• User stories in Jira that break down the requirements into blocks
• Technical documentation detailing how the project will be developed

Typically, a project scope document represents the agreed functional (and often technical) requirements between customer and vendor for seeing a project through to its conclusion. A good set of specifications should contain:

It is important to keep copies of all versions of these documents, so that you can track when features were added or removed. Date and version each release of a document and keep the archive against the Confluence project.

Hosting, API and other third party credentials

One of the most annoying aspects of inheriting an existing project is lack of documentation as to the whereabouts of production servers, credentials for third party APIs, contact details for co-locations, registrars and the like.

Ensure that any credentials that are stored with passwords are in a secure repository accessibly only internally. You don't want somebody getting hold of the keys to the castle.

Developer code comments, check-ins and time logging

Developers everywhere should be expected to comment their code thoroughly. Comment your code how you would like to receive it! You may even like to inline-comment the Jira ticket number when making a significant change as well.

All check-ins to source control (and you MUST have a source control provider) should include the related Jira ticket number. This level of tracking becomes essential when following back when work was completed and who completed it.

Lastly (and I won’t recommend any mechanisms here) keep accurate time logs of how long the pieces of a project took to complete. Not only is this important for working out billing, but it is important for giving an indication to costings the next time you have a project with similar attributes. Whilst nothing beats proper estimations, with accurate time logging you will at least have some idea.

Emails – Not even once

Emails are not accurately trackable.

All project related communication should be in the form of a Jira ticket in the relevant project if it relates to a task, or against the Confluence pages if it is general information. If you receive an important email, make sure its contents go into one of the above repositories. You’ll thank me later!