Sharp Words

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

————–
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)

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

————–
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)

There are several ways of presenting information in technical documents - this article covers what I consider to be some of the main types. For convenience, I’m going to use the term product to describe what a document is about, and the term topic to mean a small, discreet part of a document that starts with a heading of some sort.

Overviews
An overview or introduction is a high-level description of the product or part of its functionality. You might start the guide with an Overview or Introduction chapter, which describes the key concepts of the product such as what it’s used for. The overview would introduce any essential terminology or outline how the product fits into a larger group of products (product suite).

The start of each chapter of a guide should also ideally have an overview section, which describes the focus of the chapter - for example, a chapter on Working with Word Documents might explain the concept of a document and then list some of Word’s functions for manipulating documents. The overview section can also outline the information given in that chapter, perhaps giving links to the different sections.

Informational topics
Aren’t these the same as overviews or introductions?  Well, no. An overview is just that - high-level information or a summary of other information.  An informational topic contains details specific only to that one bit of functionality - for example, in the Working with Word Documents chapter, you might have a topic titled Saving Documents.

Informational topics can contain subtopics too - Saving Documents might have sections on Saving Existing Documents and Saving New Documents. Each of these subtopics has information particular just to that subject matter.

Procedures
Another type of topic is a procedure - a how to - which is often a subtopic of an informational topic.  For example, Saving Existing Documents might have a procedure called To save an open document. These are probably the meat and drink of a technical writer’s work, particularly for user and administration guide. Unless you explain to the readers how to do something, the rest of the information in the guide isn’t necessarily much use.

A procedure would usually have some sort of introduction (often in the informational topic that precedes it) to explain why a user might want to follow the procedure, and what requirements there might be for it.  I’m going to talk about writing procedures in depth in a later article though.

Reference topics
Again, these aren’t the same as informational topics although they have a lot in common. Reference topics might include, for example, a list of the options on a dialog box or the buttons on a video recorder. Information in these topics is generally presented without context - it’s what something does, not why or how it might be used.

Example structure of topics
So, for a chapter named Working with Word Documents, a sample section of the table of contents might be:

Chapter 4 - Working With Word Documents - overview
  Saving Word Documents - informational topic
    Saving Existing Documents - informational subtopic
      To save an open document - procedure
      Save Dialog Box Options - reference topic

————–
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)

I had a different topic planned for this week, but I’ve had a couple of queries lately about starting a career as a technical writer. So, I thought I’d have a go at explaining just how to go about it.

In the background
In my experience, technical writers have a variety of backgrounds. Some were engineers or developers or testers or technical support staff who were asked to write documentation and found they enjoyed it; some came straight into the job from doing something completely unrelated; some studied technical communication at college or university.

Actually, the academic route seems more common in the US; over here in the UK, there are no bachelor’s degrees that I know of, although several universities including Portsmouth and Sheffield Hallam offer MAs in tech comms. In addition, the ISTC now offers an open learning course for technical communicators.

The one thing that technical writers (or authors or communicators) all have in common is that they’re very good at writing their own language (and possibly others) and that they like or can easily get to grips with technology.

Looking for jobs
As mentioned, there are academic courses that will teach you how to be a technical writer; there are plenty of short courses on offer too, so many that I’m not going to provide links. I did do one many years ago, after I’d already started work as a tech writer, but the company that supplied the training no longer exists as far as I know.

But even if you don’t have any kind of formal training or official experience under your belt, there’s no reason not to apply for a technical writing position. Look out for job adverts for junior or graduate positions, and don’t be afraid if you don’t have the ‘degree in computing or related discipline’ or ‘degree in English’ or ‘1-2 years’ experience’ that they might be looking for. If you can show you have a good grasp of the language you’ll be writing in and can demonstrate technical knowledge or interest, particularly if you have done something relevant (designing a website or writing support emails, for example), then it’s worth trying for a position.

Note: make sure that your CV/resume is perfect! No-one is going to take a would-be technical writer seriously if there are grammatical or spelling errors, or if the layout is clumsy or confusing.

You might need to provide samples of work before or at your interview; you might have to sit a technical writing test. Be prepared (ask if either are likely if you’re not told). Again, these are good chances to show that you can do the job even if you have no formal experience as a technical writer. Be confident in your own abilities! It can’t be that hard a job after all, if I can do it…

————–
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... (3)

A lot of the suggestions in this article will depend on how well you know your reviewers.  If it’s their first time reviewing your documents, or you have a professional relationship with them rather than a friendly one, then you may need to compromise on more of the less important matters. Stick to your guns on the ones that you really care about though!

If your reviews have been done properly, you should receive two types: a technical review and a peer review.  Let’s discuss the technical review first, as it’s easier to deal with.

Technical Review Comments
In general, you won’t be the technical expert; whoever has reviewed your document should be. So, it’s a simple matter - take their suggestions for changes and updates, and apply them.

Of course, you might have described behaviour you yourself observed, or you might have conflicting comments from two or more technical reviewers. In these cases, you need to make sure that the corrections are, well, correct. Talk to your subject matter experts (SMEs) again; show them what you did and make sure that the software or hardware really is supposed to work like that - if it isn’t, someone may need to raise a bug!

Peer Review Comments
These can be harder to deal with as they apply to your writing itself. If it’s a spelling error or a formatting correction, go ahead and fix the problem. But if your reviewer has suggested changes to the wording or structure of the information in the document, you may need to think about them.

And it’s all too easy to think ‘well, I’m right’… and even if you can see their point, it’s easy to take this kind of review personally. Don’t. As discussed in the guest post by Roberto Villegas, Taking Bad Reviews Like a Pro, you can’t please all of the people all of the time, and what you think might be grammatically correct and structurally sound, another reader might not. It’s also very easy to get too close to your own work. Take a step back and assess it as your reviewer might have.

Sometimes, of course, your reviewer will just be wrong. Ignore their comments if you want, but bear in mind that if you submit the document to them for review again, they’ll just flag up the same stuff.

It’s far better to discuss the review comments with the reviewer where there is possible conflict - and this also applies if, as I mentioned can happen with technical reviews, you’ve had conflicting comments from reviewers. Be polite. Ask why they wanted something changed - good reviewers will have already said why in their review comments, but most won’t. If you think your way is better, be prepared to explain yourself. And be prepared to compromise.

————–
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 mentioned in my post about the documentation process, there are two types of review which your technical documents should ideally be put through. 

Technical Reviews
Technical reviews should be done by a subject matter expert (SME) - in other words, someone who knows all about the technical thing you’ve written about. In practice, this is usually the engineer who built the item or the developer who wrote the software, or maybe a tester or member of the customer-facing technical support staff. If, as happens a lot with my documents, a new section of document was written in response to a request by someone within the company, it’s a good idea to get them to review it too.

You might have more than one SME involved in reviewing the document.  If appropriate, flag the review copy for each reviewer so that they don’t waste time reviewing something they don’t know much about - they’ll thank you for this, believe me!

Generally, any review comments about the technical contents of the document must be applied - after all, your reviewer is the expert. Of course, if you disagree with changes they’ve suggested, or you’ve had conflicting suggestions from different reviewers, it’s always best to get clarification.  Dealing with review comments is something I’m going to cover in my next post in this series.

Peer Reviews
A peer review is generally done by another technical writer. If you’re working by yourself (perhaps for a small company, or on contract), then you need to find someone with a good grasp of grammar, who also knows about how to structure information and how to use a style guide (assuming you have one).

Your peer reviewer should be checking for:

• general readability - in other words, does the order and wording of the information given in the document make sense to a reader and user?
• writing issues - grammar and spelling problems
• adherence to any style guides - it helps if they’re familiar with the usual format and formatting of the documents you produce

Changes suggested by a peer reviewer are frequently subject to debate - for example, you might think one way of wording something is more appropriate than the way they might prefer. As mentioned previously, dealing with review comments is something I’ll tackle in my next post in this series.

Very often, your technical reviewer will check for these types of things too. It’s a good idea to tell the SMEs beforehand whether you want them to look for such issues or not. I’ve had plenty of review comments back from SMEs where they’ve spent a couple of hours correcting the wording in a document (even though that wording was dictated by the style guide) but without spending any time looking at the technical content they were supposed to check!  Also make sure that your reviewer knows what they’re supposed to be looking for - and if they only need to check a small section of the document, either give them just that part or flag it up for them.

————–
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)