Sharp Words » technical writing

Technical Writing Tuesdays: Fancy words and phrases

Catherine — Tue, 27 Jan 2009 22:22:13 +0000

This entry is part 18 of 18 in the series Technical Writing Tuesdays

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

Technical Writing Tuesdays: Measuring the success of documentation

Catherine — Tue, 13 Jan 2009 12:45:11 +0000

This entry is part 17 of 18 in the series Technical Writing Tuesdays

[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)

Technical Writing Tuesdays: Drafts and deliverables

Catherine — Tue, 16 Dec 2008 13:06:05 +0000

This entry is part 16 of 18 in the series Technical Writing Tuesdays

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.

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.
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.
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!

Technical Writing Tuesdays: Writing for the right audience

Catherine — Tue, 28 Oct 2008 12:36:48 +0000

This entry is part 15 of 18 in the series Technical Writing Tuesdays

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!

Technical Writing Tuesdays: Different sources of information

Catherine — Tue, 07 Oct 2008 17:36:03 +0000

This entry is part 14 of 18 in the series Technical Writing Tuesdays

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!

Technical Writing Tuesdays: You know you’re a tech writer… (part 2)

Catherine — Tue, 23 Sep 2008 19:37:05 +0000

This entry is part 13 of 18 in the series Technical Writing Tuesdays

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).

Technical Writing Tuesdays: You know you’re a tech writer… (part 1)

Catherine — Tue, 19 Aug 2008 19:40:39 +0000

This entry is part 12 of 18 in the series Technical Writing Tuesdays

I’m pretty busy with my new job this week, so this is just a quick post – but hopefully a fun one. I wanted to write a You know you’re a technical writer… list, but I’m low on innovation and humour at the moment.

So, I’m going to start the list, and I want you all to join in… and I’ll post up a revised list in two weeks’ time! Please bear in mind that although a lot of you who read this blog will definitely empathise with some of the entries, I’m looking for things from a tech writer’s perspective.

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!”

… ???

Technical Writing Tuesdays: The importance of consistency

Catherine — Tue, 05 Aug 2008 21:41:11 +0000

This entry is part 11 of 18 in the series Technical Writing Tuesdays

I’ve mentioned before (particularly in How to Write a How To) that when writing technical documentation, it’s important to keep a number of things about it as consistent as possible. In this post, I want to elaborate on some of the different areas in which consistency is important.

But first of all, why is consistency important? Well, it helps readers. It makes it easier for them to locate information in a document and locate, for example, menu items on the software interface.

It also helps writers and reviewers – writers don’t have to think about how many different ways they can describe the action of clicking the Open button, and reviewers don’t have to try and decide which way is better. Defining the terms and language to be used for consistency is important – most technical writers will have a style guide (or more than one) which contains this sort of information.

And it’s very important when localising documents. Consistent terms and language makes a translator’s job easier and cuts down on costs and time.

Consistency of terms
Always refer to bits of the software or hardware by consistent terms. Don’t call something a ‘drop-down list‘ in one part of the procedure and then refer to a similar bit of the user interface as a ‘combo box‘ later on. If necessary, include a reference chapter or appendix with diagrams that show what you mean by all the bits – this would be very common in a manual for a physical object.

If the product you’re writing about has terms specific to its use and area of use, make sure you define these – preferably both in a glossary and when a reader might encounter the term for the first term. For example, if part of product A deals with Woojits, then make sure you include woojit in the glossary and also explain what a woojit is in the introduction to the chapter or section about them.

Consistency of language
Keep your phrasing consistent throughout a document. For example, use either ‘From the File menu, select Save‘ or the alternative ‘Select Save from the File menu‘ throughout a procedure; don’t mix them.

Consistency of style
This might sound trivial, but always using the same formatting to indicate a button, for example with bold text, makes instructions easier for readers to follow, and makes items of interest stand out in the text.

And of course, using the same styles and formatting in all the guides for a particular company or product acts as a form of corporate branding.

Consistency of structure
If you have a set of guides related to the same product, or for different product but containing similar information, it makes sense to have a standard structure of chapters and appendixes. For example, all documents I produce for software applications would start with these chapters:

Overview of the product (a general introduction to what the product is for)
Installing the product
Getting started with the product (how to get connected/logged in, a description of the interface)

Structural consistency between documents mostly makes it easier for readers to find information, and also makes using a content management system or content re-use system easier for writers!

Technical Writing Tuesdays: Common software

Catherine — Tue, 08 Jul 2008 22:29:46 +0000

This entry is part 10 of 18 in the series Technical Writing Tuesdays

I’ve mentioned before that to do their job, a technical writer these days needs to know their way around quite a few software tools. Here’s a round-up of some of the more common ones used for authoring and publishing documents and online help.

Disclaimer: there are plenty of other software applications out there (including on other operating systems – these are all Windows-based), and a whole load of ancillary tools such as ones used for graphics. These are just the ones I’m most familiar with.

Microsoft Word
The ubiquitous word-processor. Frankly, if there’s another (better) tool you can use to create documents with, use it. If you do have to use Word, then make sure you get some training or read a good manual (in other words, not a Microsoft one) and learn how to do things like create templates and maintain styles, in order to get the best out of it.
On the plus side, it’s used by most people so it’s easy to share documents around. And if you do just want to write something simple and short (Word doesn’t do long documents very well), then it can definitely be easier sometimes to just put it together in Word. And some other software tools – such as RoboHelp and Author-IT – use Word as an output format, again because it’s used by so many people.

Adobe FrameMaker
An authoring and publishing tool (part of the Adobe Technical Communications suite). I admit to not knowing an awful lot about FrameMaker except that judging by the summaries I used to do of the ISTC mailing list, it has a lot less bugs than Word! Its main selling points are that it provides structured authoring, and that it can publish to a variety of formats. It supports XML, which is increasingly an important standard in technical documentation.

Adobe Acrobat
Used for creating and manipulating PDF (portable document format) documents which can be published and read just about anywhere in an application that can handle them. A lot of companies publish their manuals in PDF format to be distributed over the net or on CD.

Adobe RoboHelp
Another Adobe product (although it’s gone through several ‘owners’ since I’ve been using it), RoboHelp is used for creating WinHelp, HTML Help and Webhelp formats, amongst other things. It has its own source control, and supports XML.
It can be used to single-source documents (in other words, publish in ‘print’ format (usually Word) as well as help files or web pages), but it’s not really that good at it – I’ve only ever used it for creating help files. It’s got a decent WYSIWYG editor, but since all its files are stored as HTML pages, it’s possible (and sometimes necessary) to edit the HTML code directly.

MadCap Flare
This is another help creation tool, and came into being when RoboHelp was bought by Adobe (who, if I remember right, were initially going to phase it out). It seems to be doing reasonably well as a competitor; again, it offers single-sourcing, source control and XML support.

Author-IT
The tool I currently use, and one I’ve grown quite fond of (if that doesn’t sound like a daft thing to say about a bit of software). It’s another authoring and publishing tool, which lets me use the same source material to create both documents and online help (which saves time, of course). It’s also very good with content re-use, which means that I can change a sentence in one place and have the change reflected in every guide where that sentence appears.
Like RoboHelp and MadCap Flare, it has its own source control and of course, supports XML.
It has its downsides: one is a reliance on Word, and another would be the limits of the way it handles text styles. But on the whole, it’s working well for me.

Anyone got any other favourite authoring and publishing tools, or can share something about non-Windows ones?

[Note: I did have a post up called 'A missing post' because I thought I'd published and lost this one. But it turned up, with a published date of May 27th - so I've tweaked the date and taken down the other post. Phew.]

Technical Writing Tuesdays: How to write a How To

Catherine — Tue, 17 Jun 2008 17:21:07 +0000

This entry is part 9 of 18 in the series Technical Writing Tuesdays

Technical documents can be loosely divided into two types: the informational and the procedural. Each has its place, but I don’t think it’s an exaggeration to say that a nicely numbered How To procedure can be far more useful for a reader who just wants to know how to get something done and doesn’t necessarily care about the why and wherefore, or what the other buttons might be used for.

Here are my golden rules of writing a How To. Some of these apply generally to technical documents as well!

Introduce your How To.
A procedure should be introduced by something like ‘How to edit a document‘ or ‘To set colour options:‘
If there is any information that’s essential for the reader to know about the procedure, this should be included either directly before or after the introductory heading. This information could be something as straightforward as a particular mode they need to be in or permissions they need to have, or more importantly, a warning that they need to disconnect a device from the mains electricity.

Number your How To.
Using a numbered list indicates to the reader that these are steps which should be followed in a particular order.
Of course, if it doesn’t matter what order the steps are done in, then use bullet points instead. But arranging the How To in a list format makes it easier to follow.

Keep your How To simple.
If you find you’re trying to explain too many varied options in a procedure, with convoluted sub-procedures sneaking in every couple of steps, break the main down into smaller, separate ones. They’re easier to read, and easier to write as well (particularly if you use a tool that can deal with content re-use).

Write actively.
Be decisive about the instructions you’re giving (use the imperative), and write as much as possible in the present tense.
Use sentences such as ‘Click the Big button to open the Little dialog box‘ rather than ‘If you click the Big button, the Little dialog box will open‘.
Try and avoid use of the passive if possible – sometimes it’s ok to use it, of course, when not to do so makes a sentence more complicated than it needs to be.

Write positively.
Tell readers to do things, not to not-do things. For example, use ‘Save your work, then close the application‘ rather than ‘Do not close the application without saving your work‘.

Use consistent terms.
Always refer to bits of the software or hardware by consistent terms. Don’t call something a ‘drop-down list‘ in one part of the procedure and then refer to a similar bit of the user interface as a ‘combo box‘ later on.
Keep your phrasing consistent too. For example, use either ‘From the File menu, select Save‘ or the alternative ‘Select Save from the File menu‘ throughout a procedure; don’t mix them. (That’s helpful if the documents are translated, too!)