So, you've planned your document, quoted your client, and they've come back with the go-ahead. You're now ready to start writing those pages, yes?

No.

There's another step first - one that's not-so-obvious, and very tempting to skip when you have a table-of-contents sitting tantalisingly in front of you. I've worked with several technical writers who haven't bothered with this step for various reasons, and the lack of it shows in their documents, and in the amount of time it takes to get new writers up to speed on the project.

It's the creation of meta-documents. Documents about the document you're about to write. It may sound anal-retentive, but consistency is one of the most difficult aspects of technical documentation. Without meta-documents, consistency is entirely reliant on the writer's memory - and it's impossible with multiple writers.

There are two main documents to be created. One is a style guide, and the other is a Subject Matter Thesaurus. They can be created in either order, though I find it easier to create the thesaurus first. They sound like a lot of work - and they are, the first time you create them. But fortunately, 70-90% of that work can be borrowed for any subsequent project, drastically reducing the time and effort. Since they take a lot of explaining, I'll split them over two posts. First, I'll deal with the thesaurus.

Subject Matter Thesaurus - one concept per term, one term per concept

If you wanted to describe to someone how to navigate to the 'Save As' option on Microsoft word, what terms would you use? Would you tell them to 'click' the File 'menu'? 'Select' the 'button' marked File? 'Push' the File 'option'? What if you were describing how to set their Firefox preferences. Do they 'click' 'radio options'? 'select' 'tabs'?

One of the most frustrating things about a poorly-written technical document is that the writers don't use the same term for an action or concept, or sometimes even use one term to describe two entirely different actions or concepts - they may use 'select' to tell you to move your mouse over the File menu and press the left button, but then when you're told to 'select' the text, does that mean you click on it, or highlight it?

Sometimes the answer is obvious - but not always, and usually not for 'new' functionality that the user is unfamiliar with. A crucial part of techwriting is using consistent terminology so that users can work out what you mean, even if they don't fully understand what the procedure does. The rule is: one concept per term, one term per concept. If you are using the word 'select' to mean 'click left mouse button on this', then you cannot use it for any other action. Not even a similar action, like highlighting text (which is click-and-hold-and-then-drag). It must always and only mean 'click left mouse button on this'. One concept per term. Additionally, you can't use any other term to mean 'click left mouse button on this'. No "left click", or "click", or "push". One term per concept.

When you start looking at all the different things a user can do (left click, right click, click and hold, click and drag, mouse over - and that's just mouse driven actions) it becomes obvious that you're not going to be able to keep this all in your head. Especially when you start to add in things that are related to the subject, like what to call the popup dialog box, or the configuration screen. That's when the thesaurus comes in.

Creating a subject matter thesaurus

It is essentially a list of the decisions you've made about your terminology, with a little extra research thrown in. It consists of three columns:

• Term: the term, such as 'select', 'right click', 'push', 'Configuration Screen', 'dialog box' 'popup menu'
• Useage: if this is a term to be used in the documentation, the definition goes here. If it is a related term that will NOT be used in the documentation, the direction to use the chosen term goes here
• Notes: a list of synonyms, broader terms, narrower terms and related terms that will help someone reading the thesaurus to understand what you mean, if your Use definition was unclear or ambiguous. Usually a shorthand is used:
  • SY - synonym (another term for the concept. Note that any synonyms for terms you are using must also be included in the thesaurus)
  • BT - broader term (a more general term for the concept)
  • NT - narrower term (a more specific term for the concept)
  • RT - related term (a term that is not more specific, nor more general, but relating to a slightly different concept, which may or may not be a concept within the subject matter)

In this example, because we've listed 'Press' and 'Select' as synonyms of 'Click', we must also create entries for 'Press' and 'Select'. :

Repeat for each term in the document (and its synonyms). Then alphabetise it by term. 

The creation of the thesaurus serves several purposes. It helps you prepare how you will phrase your documentation, it enforces the one concept per term, one term per concept, as it's patently illogical to have more than one entry for a term, and it provides you with a lookup table when writing the document. When you're thinking "I want to tell them to select the File menu, what did I have for 'select'" - look up select, and it tells you what term to use. Your document stays consistent, even with multiple writers, and it takes a lot of the work out of thinking how to describe something.

• Add New
• Search
• RSS

Comments (0)

Write comment

Your Contact Details:

Name:

Email: do not notifynotify

Website:

Comment:

Title:

Message:

Security

Please input the anti-spam code that you can read in the image.

Powered by !JoomlaComment 4.0 beta2