Specify

What is "quality"?  For most people there are as many answers as there are people to ask.  The practical answer is: the item satisfies my needs.

The problem with that answer is the question: "What are your needs?"  Few, if any, people can give a complete answer to that question for anything they think they need – without taking time and some prompting.  That applies from a pair of shoes to a spacecraft.  The only difference is the amount of effort to arrive at a relatively complete list of needs.

And guess what?  Some people don't know what they need until you give them what they asked for.

An excellent documentation method or process for consistently specifying the right product must have reproducible steps.  And it must consistently specify the needs in the shortest possible time.

Sometimes the documentation product we need to produce is for an end customer product that is not yet fully defined – or even started to be defined.  An interesting fact of life is that many people do not know how to quickly identify the needs of an end customer product they want to produce.  (If we understand our Specify process well enough, we can offer to facilitate their definition process.  That means we can write their business requirements and product specification documents.  And that lets us write a much more accurate specification for the documentation product.)

Did you know a Table of Contents is the least useful way to accurately specify a documentation product?

The content specification is the result of asking more questions.  Let's assume we are specifying a document.  The minimum set of questions are:

 What pieces of content do we need?  Why?

Where will each piece be in the document?  Why?

Which graphics do we need? Why?

How can we test the document before we write it?

How long will it take to create each  piece of content?  Why?

How long will it take to produce each graphic?  Why?

Do you get an inkling of why a simple Table of Contents, on its own, is not the way to specify the right product for the rightprice?  A solitary Table of Contents is not the way to accurately estimate the time and the production effort.

By the way, if the Identify procedure says we have to produce a suite of documents, we apply the Specify procedure to each document separately. 

We record the answers to the questions in a specification a Technical Writer can follow to create a detailed design and produce the deliverable documentation.

In addition to the specification we also need another version of the work time line.  This is easy to do -- we know the number of people and the time needed to produce the document.

We also need an accurate assessment of the degree of difficulty of the work.  The degree of difficulty is derived by scoring a set of internal and external activities that will affect the duration of the work.  An accurate assessment will make the project shorter or longer.  A useful piece of information before you finally commit to doing the work.  The result can be the difference between working eight hour days or 20 hour days.  

If you are an experienced Technical Writer, you know what we want to avoid – that dreadful moment part way through a job when we realise for the first time this is going to be a hard, difficult job to deliver on time.

Do we need to specify every document?

When you and a companion decide to go to the movies, do you just go straight to the movie theater and buy the first tickets offered?  Or do you ask questions such as What will we see?  Where will we go?  Will we have dinner before or after?  When will we go? And so on.

Agreed we don't spend 40 minutes identifying and specifying to see a two hour movie.  Why?  Because it is a standard, well known process.  Nevertheless, you do spend a few minutes identify and specifying even well known events.

Same applies to standard documentation, such as reports, some types of manuals, some types of specifications and so on.  For example, if you have a template for the task, there may be little, if anything, to specify.

Where to next?

The next time you have to deliver an undefined job in ten hours, try spending two to three hours in the Identify and Specify procedures.  You will deliver a better product.

Does your documentation process allow 30% of the available time for planning?

If not you might like to look at an overview of the technical documentation product life cycle or some training courses,