Documentation Priorities

I was recently sent a list of about a hundred documents that were being produced as part of readying a new product for sale.  The ‘exam’ question was were we missing anything?  My first and lasting impression was not what was missing but the lack of focus that might result from such a long list. 

Of course the list was long for a good reason, there are a lot of stakeholders in any complex service and each stakeholder has their short list of critical documents.  Focus however would demand a much shorter list, to come up with a single short list it’s best to place an arbitrary limit on the number, so in this case I chose the top 5.

With this challenge in mind I decided that the best approach was to begin by thinking about needs, not documents. By needs I mean for example:

1. The customer needs to know what they are buying
2. The sales team need to know what they are selling
3. The development team needs to know what they are building and testing
4. …

So once I had this list of needs I could turn it into a handful of deliverables, each of which would need a summary presentation and a supporting document.  The list went something like this:

1. A statement of differentiation.  Both the buyer and the seller need to be clear on what differentiates our service in the marketplace, this is probably 5% of the overall service, the other 95% being common across competitors.  This short list of differentiators needs to be foremost in both of our minds.  The differentiation might exist in any phase of the lifecycle, it might be our rapid, low risk transformation approach, the way we work with the customer on benefits delivery or our great self service provisioning experience.  Whatever it is, it needs to be crystal clear for every stakeholder.
2. A service definition.  Since we are a service business we need to clearly define what that service is.  The development team needs to confirm that they have built and tested the service we define in the service definition, the sales team need to understand it, to sell it, the customer needs to know that that’s what they are buying.  The service definition is where we make things clear to everyone, what’s standard, what’s optional, what’s a customer responsibility. Also we must not make the mistake of defining only the steady state service, we need to define the transformation services and the evergreen services as well.
3. A product feature list.  We wrap products with a service, often the product is a COTS product with hundreds of features, somewhere we need to define these features because it’s rare that we will provide them all.  Sometimes a feature will have dependencies that are not present, or only work on specific devices or operating systems.  Sometimes we will have multiple COTS products integrated with in house developed components, they will have overlapping or incompatible features, all this needs to be clear to development, sales, customer and operations.
4. A cost model.  Without a service definition and a product definition it’s impossible to predict the cost of a customers solution.  A cost model combines information from both of these with infrastructure costs, licencing and support costs and information about a customers scale, complexity, topology and culture to predict actual costs.  From actual costs we can predict margin and risk and hence we know whether we want to win the business.
5. Finally we need to be equipped to answer the myriad of questions that a customer will have.  An FAQ document is the way to do this.  Ideally we will answer questions before the customer asks them, answer questions that a customer doesn’t even think to ask, answer questions that helps the customer be a ‘better’ customer, prepared for the risks and issues, ready to execute on their responsibilities. The FAQ is key to building customer trust.

Of course there are many more documents that are needed to deliver and operate and maintain a service, but without absolute focus on getting these 5 right, all of the others will suffer.  For clarification this isn’t the list of documents required to build the service, for that we would add a few more to the list.

The photo is of Windermere Lake.  I wrote this post after a lovely, but painful walk on the hills to the south of Windermere Town, to the east of the lake.  Superb views, sore feet.  My chosen writing spot for this post was Caffe Nero in Kendal, shoes off.