Sharp Words

In Writing for the right audience, one of my golden rules was Don’t use clever-sounding language just for the sake of it. As I’ve recently been revising some documents written by software professionals who aren’t technical writers, I’ve come across lots of examples of this – in some cases, long words are used in slightly the wrong way, or terms are used because they’re seen as being more polite.
A friend of mine who’s also a tech writer works a lot with documents that have been translated into English, and has given me some examples as well (thanks Voolly!) – of course, translation errors are more excusable, but the same errors are often made by speakers of English as a first language.

Here are some of my favourite (or should that be least favourite?) examples.

Utilise/Utilize
Often used in place of use. However, it has a subtly different meaning – ‘to make use of’ or ‘to turn to practical use’.
The software is utilized to perform calculations. (Not wrong, but not good either.)
This software is used to perform calculations. (OK.)
This software performs calculations. (Best!)

In order to / If you want to
Just use to by itself, please!

Within
Used instead of in. Within means inside, generally inside a physical object, which in most uses isn’t quite the word needed.

As to whether
The as to can be dropped.

In the case that
Just if will do nicely here.

Wish and Desire
Use want or require, as appropriate. Both are politer than necessary when giving technical instructions.
If you wish to -> If you want to
The desired option -> The required option

Need
You need to enter a value and A value needs to be entered are common misconstructions (the second one more in translations). Both can be replaced by Enter a value.

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts

• Leave a comment... Comments Off

[Just a note: I'm aiming to get back to a more regular posting schedule for my Technical Writing Tuesday posts. My current intention is to post on the 2nd and 4th Tuesdays of the month. Topic suggestions are welcome!]

The good news: having quality, easy-to-read, frequently updated documentation for your product can reduce support calls, entice customers and contribute to profits.

The bad news: there are very few studies out there which show this, which means that trying to convince your boss that you should write more documentation and you need more resources (training, new staff and so on) can be pretty difficult.

If you’re lucky, your company knows the worth of its documentation, at least qualitatively. However, if a technical publications department is asked to prove its worth quantatively, it isn’t always easy. And in these days of recession and tightening belts, it’s possible that we technical writers may have to justify our positions.

There are a few ways of getting some actual numbers about who’s reading your documentation and about its benefits. As mentioned, there aren’t a lot of studies out there – at least not necessarily ones readily available online – which give examples of the cost benefits of technical writing (the type that managers care about), so you’re going to have to develop your own way of quantifying your contribution.

If your documentation is hosted on a website, it’s pretty straightforward to set up some sort of hit counter. These come in various levels of sophistication, from a simple counter to something like Google Analytics which can tell you exactly when, from where and how readers reach your site – and even why, if they reach it from a search, which also lets you see if they were looking for something you don’t currently have. Some knowledge base software also enables you to log readers’ queries, so you can see if there are gaps missing in your documentation set.

If you’re launching a new knowledge base, or releasing guides or help for a previously undocumented products, ask your product’s support team to keep a note of how many calls they used to get about the product, and how many they get after the document’s release. This is possibly one of the most useful statistics you will ever have, as it can be used to demonstrate how much less support time is taken up compared to the time invested in creating and maintaining the knowledge base or guide/help. (Of course, the support manager might not be so delighted if they were hoping to expand their team!)

Check with your sales people too, to see if any customers have demanded particular documentation; some might even make it a condition of the sale. Certain industries have legislative requirements for documentation as well. If you can prove that a sale was made because a guide existed – or you could produce one at short notice – then you’ve got a very solid argument for the ‘value added’ by the tech pubs department. (I hate that phrase, but it is a useful one sometimes!)

Further reading: Cherryleaf – Benefits of using a technical author (has some numbers towards the bottom as well as other useful information)

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts

• Leave a comment... (1)

As discussed in previous posts, technical documents typically go through several draft phases. A first draft is often incomplete, and it can take a few more drafts and review cycles before a document is ready to go out to its intended reader (and can be classed as a ‘deliverable’).

But how can you stop well-meaning support agents and sales people getting hold of a draft and passing it on to the customer? How can you stop unfinished documents being published to your website with glaring errors and ‘TO DO’ markers?

Well, you can’t always prevent your drafts getting out into the wider world. But you can minimise the damage.

1. Use a watermark or header/footer to mark your documents as DRAFT. Having that stamped on every page makes it very clear that the document is not complete.
2. Enforce source control and don’t let people have access to unfinished documents if there is no reason for them to have! Of course, this isn’t always possible; and if there’s no central control (you!) to make sure that everything that goes out is fully complete and wholly accurate, then that just makes preventing disasters twice as hard.
3. So… Encourage disclaimers – if you don’t have control over what goes out publicly, then at least make sure that any colleagues who may send documents out know to do so with a disclaimer that the document isn’t finished.
   Have a disclaimer added to the front page of any draft documents too, as belt and braces!

If draft documents are regularly given out to customers (with or without your say-so), then it might be worth having an ‘early adopter’ scheme. Create a ’special’ draft (perhaps when your document is 90% complete or just one or two reviews away from being signed off) which can be given to customers by support and sales staff. Call it a beta release of the document, if you like, in line with software naming!
One advantage of this method is that you instantly get an extra set of reviewers – and importantly, they are the type of people who the document is aimed at, which means that you get exactly the right sort of readability review that many tech writers can only dream of…

PS: Thanks to Andrew for the topic suggestion. Other suggestions for topics in this series are very welcome! I’m up for covering general issues like this, or for writing more specific how-to articles. Or anything related to technical writing, really!

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts

• Leave a comment... Comments Off

Write for the right audience is (or should be) one of the golden rules of any type of writing. For example, if you’re writing a novel for children, don’t bog the story down in too much flowery description; if you’re preparing a pamphlet listing rubbish bin collections, keep timetables and lists simple enough for people of any level of education to understand.

This simple rule can be broken down even further for technical writers.

1. Know the level of your audience.
Are you writing a manual for novice users? Are you writing one for system administrators or developers who will probably know the technical concepts better than you do? Are you writing for an academic journal where complex terms will be fully understood by readers?

Make sure you use the right level of language for your readers, and try to avoid either confusing or patronising them. If you have multiple levels of readers, you can pitch your document somewhere in the middle, but don’t forget to explain things for those with lower levels of prior knowledge.

2. Explain unfamiliar concepts.
This ties into the previous point. For someone who has never used a computer before, include a diagram which names each part of a window, for example. Don’t assume that they will know how to click a button – explain it!

Do likewise with other terms and concepts that may be unfamiliar – it’s better to explain it than to leave someone floundering. People who know what it means can skip it.

This is where glossaries and appendices of reference material can be really useful, but don’t force readers to have to go looking in the glossary fifteen times a page.

And always remember to spell out acronyms, initials and other abbreviations the first time they are used!

3. Don’t over-complicate.
Don’t use clever-sounding language for the sake of it. It doesn’t add anything to your writing, and can be confusing – and difficult to translate! There’s no need to write ‘There is no possibility that you can’ when ‘You cannot’ works much better.

Don’t use jargon for the sake of it, either – or if you must, explain it (as per #2).

4. Don’t over-simplify.
This might sound like a contradiction of the previous point, but it isn’t. Sometimes technical documents (and I include other types of scientific, medical and scholarly documents here) contain complex concepts which will lose their significance if reduced to language that’s too simple.

If you have to explain complicated ideas, keep your explanation as straightforward as possible and explain terms that will be unfamiliar to your audience where necessary (as in #2); but don’t dumb it down to the point that you lose meaning or patronise your readers.

In summary: know the level of your readers and write to suit them! Even consider breaking a document into ‘basic’ and ‘advanced’ user guides if necessary. Don’t try to be too clever and keep things straightforward, but avoid making your writing too stupid, or so simple that your readers are annoyed.

All of which sounds complicated… but it isn’t. It just takes practice – and where possible, some guinea pigs to test your documents on!

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts

• Leave a comment... (2)

In past posts, I’ve mentioned that information gathering is one of a technical writer’s more essential tasks. Here, I’m going to discuss some of the possible sources for information about the product you’re documenting.

Requirements and specification documents
Some companies produce requirements and specification documents when developing a new product or piece-of-product. In my own experience, when these are written well, they’re invaluable for the technical writer – they contain information about what the product is supposed to look like, and what it’s supposed to do and why and how.

If you have to write a brand-new document (or bit of document) about the product, then these documents should be your starting point for estimating how long it will take, and for drawing up an outline of the information to be included.

Information about bugs
It’s important to have access to the database in which details of issues/incidents are stored, where possible. This means that you can see what bugs have been fixed in the product and determine if and how the fixes might affect the documentation. Some companies will have a system where faults in the documentation are logged as bugs, too, which is a useful way of tracking your own work.

Engineers
Always, always, make sure you have access to the engineers (software or hardware) who have worked on the product. They are your primary Subject Matter Experts (SMEs), and therefore the people best placed to give you the low-down on how the product works.

Developing a good relationship with engineers and their managers is important too – they are also the people you will want to review your documents for technical accuracy. You need them to understand why the documentation is important and to be willing to give you their time and assistance.

Testers and support staff
Anyone else who has worked with the product, such as testers or technical support, can also give you a lot of insight and help. They generally use the product as a customer might, which means they can give you that point-of-view you might not otherwise have access too. In addition, they will often have documents of their own which can be used (test cases or FAQs, for example).

Playing with the product
No matter how much ‘paper’ knowledge you have of a product, and even if you’d been on the receiving end of demonstrations, nothing beats having practical knowledge of your own. Wherever possible, make sure you get a copy of the software or a model of the product to work with – it makes writing descriptions and procedures so much easier!

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts

• Leave a comment... (2)

Got a couple more to add (thanks Dawn for #3!)- please do contribute!

You know you’re a technical writer…

… when you feel emotional and/or physical pain at the sight of an out-of-place apostrophe.

… if, when faced with an engineer asking you questions about a product you document, you say in a tired or exasperated tone: “RTFM!”

… when you can’t stop deleting those (invisible to everyone else) spaces after the full-stop at the end of sentences.

… when you consider taking a new electrical iron back to the shop after having your eyes assaulted by the flagrant misuse of its and it’s in the manual (even though you’re probably one of the few people to actually read the manual).

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts

• Leave a comment... (2)