Details

Last Updated: 09 January 2014 09 January 2014

Hits: 10601 10601

Design

If this is a "standard" documentation task – meaning you have a template (because the document is the same as last time), you are done!

Almost.

Even re-run documents, unless they are fully automated and data-driven, will have different content.  Sometimes that needs a bit of Design.

The Specify process produces a detailed specification of what is in the documentation product.  But there are no words about how it should be laid out, where to place the graphics and so on.  Often we might say the layout is obvious.  Why?

If you are content with more-of-the-same production, then you are done.  But if you have the opportunity to dare to be different, cease it!

The quickest and simplest way to Design is with a pencil, eraser and lots of paper.  (In film and television, this is called storyboarding).  You may only need three storyboards or you may need thirty.  It all depends on the document and your imagination.  (The only thing you cannot do, without approval, is change the specification.)

Why use words at all?

How many ways can you present a "graphic"?

Carrying a load of nonsense?

We received a request to "write a user guide for our freight handling software".  The conversation went something like this:

"Why?"

"Because we are rewriting the existing application in Visual Basic"

"Who will use it?"

"The existing staff."

"Will all the functions be the same?"

"Yes."

That was all we needed for the Identify procedure.  We came to the conclusion a manual was going to be a waste of our time and their money.  So the Identify procedure proposed a document that would take less than a week to produce and everyone could use instantly.

The client loved the idea.

The specification was about five lines on a page.  The Design was a storyboard of the documentation product on the remainder of the page.

What did we produce?

This email address is being protected from spambots. You need JavaScript enabled to view it. and find out if you are right or get another clue.

Details

Last Updated: 07 February 2014 07 February 2014

Hits: 9221 9221

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,

Details

Last Updated: 06 March 2014 06 March 2014

Hits: 9327 9327

Identify

What is today's biggest question?  Are you who you say you are?  We all want accurate identification.  In Technical Writing accurate identification is about How, Who, What, When, Where, Why.

To deliver the right product at the right price, we have to ask a lot of questions.  But before we do, let's make sure we are using the same terminology.

What is a technical communication product? Anything that conveys the right message to the right person at the right time to get the right result.

We won't know the right message, the right person, the right time or the right result until we have asked the right questions. The questions are the start point of the Identify procedure.

As our company or our customer sells products, we will call the technical communication product, documentation.  We won't know what the documentation is until we finish the second last step in the Identify procedure.  

The documentation could be a video or an audio recording, a promotional give away, a wall chart or an electronic or paper document.  And it could be many of any of these things or any combination of these things.  Once we identify what the documentation is, we can call it by that name.

Our company or our customer sells a physical item, an idea, a service or a pattern of behaviour.  So our first step is to start identifying our company's or our customer's product.

What is the product?

What stage of development is the product in?

Who owns the product now and later?

Who knows and understands everything about the product?

Where does the product fit into our company's or our customer's business activities?

Is this product part of any other initiatives?

Who will maintain the product?  Why?

Who will support the product?  Why?

What will the product be used for?  Why?

When will the product be used?

How will the product be used?

Who will use the product?

What knowledge does the end customer have about the product?  Why?

What knowledge does the end customer need?  Why?

What skills does the end customer need?  Why?

Who has what assumptions about what the documentation will look like and what it will achieve?  Why?

 Are you getting a feel for what we need to successfully identify the right technical communication documentation?

Sometimes we are dealing with straightforward documentation.  At other times it might be a suite of documentation for a huge project.  So the Identify procedure also looks at what media the documentation will be on, the delivery format, the advantages and disadvantages of this approach over that approach and so on.  This is when we finally choose the technical communication product.

And guess what?  Sometimes is it not what the our company or our customer is expecting.

Example: In case of combat, press Help?

One of my clients asked me to spend a year writing help text for a piece of live combat equipment.  As I had been a soldier, I knew no-one in combat is ever going to press help!  So I asked the client where I could read the requirement.  

The client said it was not in the specification but in "correspondence".  So I asked to see the correspondence.  The client could not find it after a quick search, so gave me permission to search for it, including in the archives.  

At the end of two weeks I confidently stated there was no written requirement on the project.  I suggested we sent an email to the prime contractor saying we were ready to upload their help files and could they let us know when they would be delivered.  

The was no answer and no help text was delivered over the remainder of the project.  The client saved themselves a pocketful of money for writing documentation nobody had requested.

Two other things to do

There are two other steps to do in parallel with the Identify procedure.  We need to prepare a first draft of the probable timeline for the work and make a first estimate of the degree of difficulty of the work.  

If we know the expected due date, it is easy.  If we don't know the expected due date, that is easy too -- nothing to do!

When we know the expected date, we can use our first estimate of the degree of difficulty to see if the work is likely to be finished by the expected date.

Where to next?

Does your Identify procedure bring you to this point?

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