The page versus the slide

What differentiates the page from the slide, the PDF from the presentation, documentation from training?

Forget, for the moment, documentation via videos and the like, what I want to do here is look at traditional documentation, the written word, versus traditional frontal training and try and identify the overlap between the two. many times I have argued that documentation and training are two sides of the same coin, that training is just another way of presenting material that is otherwise covered in the documentation, and thus documentation teams and training teams should be grouped under the same organizational umbrella.

I know that this is not 100% true, since in training there are always the little tips and tricks, that in the end can make or break the user experience, which nevertheless, for a plethora of reasons never make it into the documentation. But there are solutions to this as well without resorting to a week at a course somewhere exotic, like forums where users get to share their experiences (for good and bad).

Tips & Tricks: Getting the developers attention

Scenario 1: You have to document something and need help from the SME. You have the time for this but the SME hasn’t or doesn’t want to spend the time with you.
Scenario 2: You have produced your 700 page PDF masterpiece (or 4591 HTML pages) and want the development team to review it for accuracy. You wait and wait but nothing is forthcoming.

The usual response to these scenarios is to have a firm methodology in place where everyone required to ensure the documentation is complete and correct signs off when they have done their bit. In this way, shoddy reviewing or insufficient explanations are the responsibility of someone else. But, I, and I alone, am responsible for my work, or my team’s work. I might be able to push the blame for bad work on to someone else’s shoulders, but I don’t want to. I don’t want bad work to start with. So, how to I get the attention of the developers to describe what they are doing, and then to review my interpretation of what they are doing?

Well the first thing is to make the developers understand that I am not a secretary with typing skills and that I can bring added value to their output. This can only be done by showing the developer that you understand their world to some extent. I don’t intend going through the old argument of what is better, technical understanding or writing skills, since in the end both are important – and the key word here is both. You have to prove to the developer that you do understand the software (caveat: I deal with complex software so my all important audience are also developers – thus this post is mainly aimed at this type of writer). When I managed a team of writers I would never let a junior writer approach the developer to find out information without first answering the “bleeding obvious” questions, and then priming the writer with a couple of intelligent (at least to the developer) questions. Only when the developer realizes he is talking to someone (almost) on his intellectual level, will he spend time describing whatever it is that needs describing. Bit by bit the junior writer gets to really understand the product until he can ask intelligent questions without my help – and then attain the glorified status of senior writer.

Another trick is to go through the whole product, working with it and reporting bugs found, both from a language perspective and from a usability perspective. The more serious the bugs, the more the developer realizes you have something to offer.

Make it a point to be a player when it comes to usability issues. In my current position the chief developer (also the CTO of the company) includes me and the usability expert on all changes made to the GUI – he appreciates the positive impact my negative input has on the end product.

Become established in the company for something else. In my case I produce a newsletter, that makes fun of individuals in the company (in a friendly way). People love to see their names in print, even if it means they are being insulted. And guess what, they are more willing to talk to me about what I need to talk about.

When it comes to reviewing, don’t expect the developer to read the same piece more than once. You’ll be lucky if it is read thoroughly even once. When you have material to review, take the additional time to break up the material per the relevant SME. Out of the 700 page masterpiece, supply SME 1 with pages 12-19 and 700-732, SME 2 with pages 20-22 and 29-32, and so on. If this is a second review, mark the changes so that the developer knows why he is going through it again. Don’t just supply the whole caboodle to the developers to sift through with a sign-off at the end. You’ll get your sign-off and cover your backside – but no more. You need positive not passive feedback. A signed OK or requisite number of Likes on your Facebook page doth not a review make.

Taking the initiative

It doesn’t matter what the profession, there is always a totem pole, whereby the tea lady is at the top, or on a par with the CEO, and the cleaner is at the bottom, and in the hi-tech world on a par with the technical writer. If the cleaner does not speak English the tech. writer might move above her (sexist I know), but if she does speak English, well she could probably write the user guide so she deserves to be on the same rung of the ladder.

No-one ever has time for the poor sap who has to explain the genius of the developer to the waiting masses. And if the masses don’t like the product, it is only because the writer didn’t explain clearly enough its brilliance and simplicity of use.

So the world has little time for the writer, unless of course they have something that needs a “page or two” yesterday, and that should take at most, what, let’s say thirty minutes to rattle off, and definitely no more than an hour.

I exaggerate slightly, or do I? The question is not my levels hyperbole but rather how you handle these situations.

First, the idea of the cleaner or secretary or anyone with a smidgen of English being able to create the sort of masterpieces that you churn out for breakfast. The only way to combat this, apart from letting the secretary try her hand at putting together the guide for the next version, is to gain the respect of the developers. This leads into the argument about technical expertise versus writing acumen, which was covered in The half-way point. Suffice it to say, you must be able to ask pertinent questions at pertinent times to be pertinent.

The next point to tackle is the misguided concept that what we do is so easy that it doesn’t take very long to do it. It’s about as easy as cooking. Most people can boil an egg, but to get just the right result, a soft yolk and hard white, etc. takes practise. So when you think it will take a couple of hours, double the time when giving your estimate, and even this is probably not enough, because what they want will change, and other people will demand your time. So a net two hours of work on the document might actually take a day to produce. After completing whatever it is, sit on it. Don’t rush to hand it in. Waiting a half day means that when you look it over again, before delivering it, you are looking at it with a freshness that means you are more likely to see the mistakes that were not there a few hours earlier. Also, however important, I am willing to bet that they will not use the document immediately, but will also sit on it – so cut their “sitting time” and not your own. Also, the quicker you deliver the greater the expectations are for the next time, when you really will need the extra time.

And finally, to wrap up both the points dealt with: Ask sensible, pertinent questions. In the first scenario, you start to gain the respect that helps you get the information you need to do a good job. In the second scenario, asking a relevant question buys you time as they figure out an answer. Being passive and waiting for them to ask where is the promised masterpiece puts you in a weak position. Being active and asking for additional information to help write the piece buys you time and kudos.

To sum up: When in doubt ask (but make sure what you ask for is valid).

Asking the right question

What is the first question you need to ask before you can start to document something? Probably, the answer to this question is: who is the documentation aimed at. You need to know this even before you know what the thing is you are going to document and how to use it, etc. Once you know your target audience you can start to focus on the thing to document, learning what it does and explaining how to use it. It is for this reason that Reader was the first entry in my list of ten commandments.

Knowing the audience clarifies lots of non-issues. For example, is it logon/logoff or login/logout, or login/logoff, or log in and log out or any other combination you can think of.

Guess what? It doesn’t really matter if it won’t matter to your audience. So if you are writing for a bunch of senior developers they will gloss over the words and jump to the bit that interests them. When tested on what they read, they will say, for example, “the documentation explained how to log on and off, even if the actual terminology used in the documentation was login and logout. So once again, don’t get bogged down with what is absolutely right, since at the end of the day what is absolute to you is only relative to your reader.

Of course, if you happen to know, or can very, very, very quickly ascertain what is used (login/on, etc.) then use it. And this is the other consideration, it doesn’t really matter what is right or wrong, what matters is what is used. So if the audience uses the “totally incorrect” log on/logout, combination (and the space is purposely added to this example), don’t start trying to change it because you think it is incorrect.

I have mentioned on many previous occasions how language is a living entity and changes with time. So what was correct yesterday is not necessarily correct today. How many of you refused to watch Star Trek, switching off the television because you were affronted with the use of the word boldly as a verb – to boldly go where no man has gone before (or as was made politically correct in the next generation, to boldly go where no one has gone before – without reference to man going anywhere)?

How many of you are happy to say “you and me …” and not “you and I …”?

I suspect that the number is fairly small. So we all feel for the language, and want it to be grammatically perfect, but only when it suits us.

It is interesting that in one thread about what is the right way to say something it took four posts until someone piped up that it depends on the usage in that company as to what is correct or not. Which brings us back to my initial premise, the first question is who is the reader and what do they expect or want to see written.

So what you always need to consider is: Are we writing literature or bog-standard material for a very specific audience?

Don’t get me wrong, use of English is important but also remember that Shakespeare, who was writing literature, introduced many hundreds of words in to the English language. He obviously did not feel constrained by the grammatical rules of his day.