- 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,
- Details
- Last Updated: 14 November 2013 14 November 2013
- Hits: 27282 27282
The discipline of a profession (overview)
The discipline is the same for every profession: To consistently identify, specify, design and deliver the right product for the right price. What is different for every profession are the tools and techniques applied to each of those steps and how long it takes to acquire the starting point knowledge. For example, a doctor has to study longer than an accountant and the range of tools a doctor uses is much larger than an accountant. But for this overview, we will look only at the way the discipline of the profession applies to accountants, lawyers, doctors and technical communicators.
- Details
- Last Updated: 14 December 2013 14 December 2013
- Hits: 9963 9963
Consistency
How often do you turn into the wrong drive-way when you go home? How often do you forget your income tax?
We don't make these mistakes often because we have some kind of procedure to make sure we do the right things at the right time.
Speaking of paying bills, did you know that running a house is exactly the same as running a business? It is the same – only the number of noughts are different.
And so it follows, if we achieve consistency using processes and procedures at home, we should do the same in business. When we have a repeatable method, process, sequence or model, we don't accidentally miss bits along the way. If we have an excellent method or process (comprehensive and thorough) we can cut corners when we have to, because we will know which corners we cut and what we have to fix up later.
Excellent methods and processes are usually scalable. As Technical Writers we have to be prepared to be given a brief for delivery within in a few hours. If we want to do professional work, we cannot afford to forget any steps just because the time is tight. So if your method or process cannot handle time frames of a few hours (to deliver a single document) or up to a few years (to deliver a suite of documents), you have the wrong method or process.
People often assume each step in a method or process has to be carried out the same way every time. Often that is true. I know a doctor who drilled a Burr hole in an accident victim's head using a ski-binding drill from the nearby ski shop. He followed all the steps – but used a different tool to suit the circumstances.
For example, an excellent method or process does not insist you have to write a plan using Microsoft Word. There is nothing wrong with writing a plan with a pen and a paper serviette sitting in a cafe – if it suits the circumstances. What is the difference? Several hours of time. That is all – provided you know your method or process well enough.
That means your process must be easy to remember and easy to apply. And an excellent method or process will often say nothing about the tools for doing the work.
An excellent method or process is usually sequential, but it can also be circular at the same time. Depending on the method or process, we may spend a long time on say, Step 1, but have quick visits to the rest of the steps before we finish Step 1 to check we are still on the right line. The same applies to Steps 2 and 3 and so on. At each step we check where we have been and where we are going.
So if consistency is built on an excellent method or process, do you have an excellent technical communication method or process?
What does it contain?
How did you create it?
Is it written down?
Do you teach it to others?
Does it handle any size job and any number of people?
Do you show or describe your method or process to your boss or your customers so those people can see you know what you are talking about?
Would you like to bet three months salary or the amount of your next invoice that your process can deliver the right product for the right price?
It not, you might like to look at an overview of an excellent process or some training courses,
Reconstruction notice
This site is (slowly) being re-constructed.
If you click on a page and find no content -- don't worry, it will be there soon!
The menus give you an idea of what is coming to the site.
Thank you for your patience.
In the meantime you are welcome to contact me:
