Delivery Documentation

When buying a car, there’s a reason you are given such a comprehensive user's manual to cover everything that the salesperson or technician was unable to show you how to do in the first demonstration. Things like what to do when the "Check Engine" light comes on, or which grade of oil to use when it comes time for an oil change. Although you may not reference it often, when needed the supporting user manual is worth its weight in gold. The user referencing it in time of need can save frustration, time and money; but more importantly, without it, there is the possibility of the owner causing serious damage with potentially dangerous outcomes. Imagine someone over inflating their tires, and having them fail while driving on a highway.

 

 

 

 

 

The same principles apply to documentation in a web development environment. Regardless of how often it is referenced, or the implication of the task being referenced, not having it in time of need causes unnecessary client frustration and at minimum, a poor user experience. The worse case scenario can mean site outages and significant opportunity cost from brand damage or revenue loss. A successful project that was delivered on time and budget can be tainted; truly, a lose-lose scenario.

 

Delivering complete and relevant client documentation can be tricky, and ultimately you do need to determine the comfort level of a client to achieve this. Some pointers to keep in mind for successful documentation:

 

1. Enrich your documentation - Screenshots (and sometimes even videos) are great to include in the documentation. Enriching your documentation with media adds a level of polish that will really set your team above the competition.

 

2. Take nothing for granted - It goes without saying that everyone has their own comfort level when it comes to the care and feeding of a website. Even within the client's content team, there may be a range of skill levels. The best thing to do is cover as much as you can, short of giving a tutorial on how to use the browser or OS.

 

3. Get an outside opinion - While it can be good to have a developer or solutions architect on the project write most of the documentation, it is usually worth having someone not as familiar with the site attempt to actually attempt to *use* the documentation. It may even be worth getting someone non-technical to look at it, depending on the comfort level of the client.

 

A good way to begin authoring client documentation is to form the structure of it from the actual requirements documentation that was drafted during the discovery phase.  The reason for this is two fold: it gives you hierarchy and chronology to the document, and it also ensures that you don't miss outlining any of the features painstakingly built out by the developers.

 

Consider the following scenario: The tech firm, Web Monkeys, delivers a completed project to their client, Hotels for Alpacas. The client is extremely happy with the way the project played out, from discovery to delivery.

 

Eventually, after extended use of the website, they realize there are some particular pain points that put undue stress on the content team. Hotels for Alpacas call up Web Monkeys to explain the situation, but there is a problem. The entire original web team has moved on to other opportunities. All that Web Monkeys can do to address their clients' concern at this point is to spend a lot of unnecessary time and effort to solve their issue. This is worsened by the fact that the original developers built a fix for the issues in question, but did not document it!

 

I think by now, it is obvious that this (and many other) post-launch issue could be alleviated or avoided altogether fastidiously documenting everything we do. As this is such an important topic, we will be continuing our approach to documentation in the coming months with subsequent posts outlining best practices in documenting specific areas of a project -- stay tuned!