Contents
Description
Required knowledge
The process of documentation
1. The first push
2. The first review
3. Fleshing it out
4. Going down to the wire
5. The final review - signing it off
Ways in to technical writing
Skills summary
Essential
Helpful
Recommended Reading
Web links
General information and links
Specialist agencies for technical authors
About the Author

Description
In the most general terms, technical writing is the documentation of a computer system for its intended user. In practice this could be something like:

• writing a manual for a Word Processing software package
• developing an online help system for a stock control system
• re-writing the specifications for a circuit board
• writing the instructions for a computer game
• listing and explaining all the commands for a programming language, and publishing them as a web site.

Required knowledge
As you can see, it’s likely that a technical writer could be called on to document a range of highly advanced subjects. It’s not necessary, however, to know these subjects inside out. In fact, it’s often an advantage not to know too much about them beforehand. This means you can use your own learning experience to inform your documentation.
However, it’s essential to be computer literate. You will be using computers both in the act of writing, and in the publishing of the documentation, which increasingly doesn’t involve paper. Often documents have to be published electronically, and you’ll be expected to figure out how to do this by yourself. That said, if your writing is demonstrably good, most employers will allow you to train (or at least give you time to experiment) in these techniques.

The tools of the trade
Although knowledge of a specific word-processing package is in practice not important, many employers look for experience of the following, in order of importance:

• Microsoft Word
• Adobe Framemaker
• Corel Ventura
• Quark Xpress.

As for online publishing, some familiarity with the following might prove useful:

• HTML
• Microsoft Frontpage
• HTML Help
• Microsoft HULK
• HDK.

The process of documentation
This section will be a brief outline of a typical documentation process, based on my own experiences. This may not be the best way for you, and many companies will have their own procedures in place. This is merely meant as an example of the type of tasks involved in a typical project.

1. The first push
In my experience, about 60% of the actual documentation is done without speaking to another soul. There is almost always something to start on, be it technical specifications (very dry technical descriptions of the system), or, if you’re lucky, the system itself. If you’re even luckier, both.
When you’re faced with these sources, and a blank Word document, you have to begin to decide what it is you are documenting, and for whom. This will allow you to begin to structure the information. A draft table of contents, with a sentence on each chapter, is a good way to do this. Some pointers:

• Try and break down the system into digestible parts, and order them in such a way that the intended user won’t be presented immediately with too much in-depth information.
• Tell it like a story; introduce your characters, flesh them out, then connect them and involve them in the big picture.
• Learn the system and document your own learning process. Where were the sticking points?
• Harangue the developers of the system. If something seems confusing to you, ask them why it’s done that way. They may change it, or there may be a good reason that you hadn’t yet discovered. Usually you’ll just have to document it as best you can.

2. The first review
After you’ve got an outline, show it to the key reviewers. These will be agreed beforehand. For example, there might be:

• technical people, preferably the actual developers of the system,
• strategic people,
• a peer reviewer (one of your writing colleagues, or at least someone who can string a sentence together),
• a project manager.

About eight is the maximum number of people you should have reviewing a project. Possibly extra people will be involved for specific areas.
(It’s important that you identify these people at an early stage, and that they understand their responsibility. One of the less savoury aspects of documentation is constantly having to pester people for their comments.)
Here are some tips for the review process:

• Most reviewers will want their proof copies in paper form - most reviewing is done on the train, in the smoking room, or in the loo.
• Attach a cover sheet explaining the aims of the particular document, and a form on which they can summarise their changes and sign their name. Also include a due date.
• It’s a good idea to draw up a chart for your reviewers, allowing them to document their changes. Where you disagree with changes, mark these with your explanation, and send it back, so they can see your point.
• Invent a tracking system that keeps everybody in the loop. A simple table that shows who changed what. It’s worth the extra work to nip any disputes in the bud.
• Disputes will occur. For example, one of your reviewers will make a change, and on the next review, another reviewer will change it back. Go and talk to them, and find out if it can be easily resolved. It normally can.
• If you end up with a lot of insoluble disputes, among several different groups, call a meeting, and don’t let them leave until you have a definitive version.

3. Fleshing it out
Once you’ve got your structure, you’ve got the long haul ahead of you. In many ways, this is the easiest part. Just focus in on your outline document, and leave no stone unturned. If your reviewers are good, they won’t let you get away with skipping the difficult bits. If you’re lucky enough to work as part of a team, your team mates will help you; often just trying to explain a difficult concept to someone will unlock the door.
Send out reviews for each section, as with the first review above. If you find a section’s rather long, break it up. Your outline is not set in stone. You’ll find that as you discover more about the system, the structure of your document will evolve.

4. Going down to the wire
Up until now, I’ve described documenting a system which is static and defined. This is almost never the case. As you are writing, the developers will be developing, and you’ll find that when you get the latest version of the system, many of the things you have written about don’t exist any more, have moved, or have been replaced with something different. The only thing you can do is take a deep breath, rewrite the section, and send it out for review again. Repeat this process until you run out of time.

5. The final review - signing it off
Before you publish, you must get signatures from all the key reviewers saying that it’s complete and correct. Often this can be painstaking as someone will make a last-minute change, and you’ll have to send this part out for review again, and then start the sign-off process again. If it’s just a small change you can usually agree that a further review is not necessary, and you can go to press.

Ways in to technical writing
First of all you need a well written, concise CV. Concentrate on any writing or communication you have done, and include examples attached to your application.
Attempt some technical writing. Try critiquing and rewriting some bad documentation, be it for a simple piece of software, or an electrical appliance.
In terms of looking for openings, you should also contact the main specialist technical writing agencies:

Kudos
9/10 Westminster Court, Hipley Street, Woking, Surrey, GU22 9LG
Tel: (01483) 747227
Fax: (01483) 747337/771279
E-mail: 100666.2312@compuserve.com
Web site: http://www.kudos.co.uk

TMS
Hambledon House, Catteshall Lane, Godalming, Surrey, GU7 1JJ
Tel: (01483) 414145
Fax: (01483) 419717
E-mail: marketing@tmstoday.com
Web site: http://www.tmstoday.com

Digitext
13 High Street, Thame, Oxfordshire, OX9 2BZ
Tel: (01844) 214690
Fax: (01844) 213434
E-mail: bob@digitext.co.uk
Web site: http://www.digitext.co.uk

Although they deal largely with contractors (experienced freelance workers), they will be able to help and advise you. Recently, a few MSc courses in Technical Writing have started. This may be useful, if you are enthusiastic about studying, but not necessary. Most technical authors I have known come from backgrounds as varied as Philosophy, History and Psychology, as well as computing, and many have not studied to graduate level.

Skills summary
Essential:

• Writing skills
  It’s obviously essential for a technical author to have a decent command of the English language, and to be able to harness it in the controlled and precise way required to write technical instructions.
• Communication skills
  The most difficult and time consuming part of writing is communicating with technical people to ascertain the concepts and functions of the system. It’s likely that you will also be expected to arrange and chair meetings to discuss documentation problems.
• Ability to work under pressure
  Technical writing is often the last part of the development process before a system is released. You will find that you will be given the minimum amount of time to produce your document, and that the system will change in this time, so time pressure is unavoidable.
• Organisational skills
  Without the benefit of good systems and processes, you will drown under a sea of scribbled-on paper when it comes to review time.
• Diplomacy
  When you are considering reviewers’ comments, you may need to tell your project manager that he can’t spell, or his grasp of grammar is incomplete.

Helpful:

• Enthusiasm for writing
  Although you won’t be able to write with complete abandon, an enthusiasm for writing will help you work through grammatical and conceptual problems, and discuss these with your colleagues.
• Patience
  When the same section has been for review for its sixth time, you’ll need patience.
• Eye for design
  You may be called on to create simple diagrams and tables. Also you will have to create visual styles for the documents. This requires an eye for the aesthetic, and some basic knowledge of typography.

Recommended Reading

• Writing Software Manuals: A Practical Guide by Martyn Thirlway, Prentice Hall; ISBN: 0131388010 ;
• BS7649 (British Standards for Software Documentation)
• The Microsoft Manual of Style for Technical Publications by The Microsoft Corporation
• Fowler’s Modern Usage
• Illustrating Computer Documentation by William Horton, John Wiley
• Designing and Writing Online Documentation : Hypermedia for Self-Supporting Products by William Horton, (Wiley Technical Communication Library)
• How to Communicate Technical Information : A Handbook of Software and Hardware Documentation Jonathan Price, Henry Korman, Cummings Publishing Company; ISBN: 0805368299
• The Elements of Technical Writing (Elements of Series) Robert W. Blye, Gary Blake, Macmillan; ISBN: 0020130856
• The Art of Technical Documentation Katherine Haramundanis, Butterworth Heinemann; ISBN: 155558182X
• Type & Layout : How Typography and Design Can Get Your Message Across-Or Get in the Way Colin Wheildon, Mal Warwick
• The Non-Designer's Design Book by Robin Williams

Web links
General information and links

• http://stc.org/region1/ukc/stcukhome.html
  The UK branch of the world-wide Society for Technical Communicators. A variety of useful information here, including CV and job finding tips.
• http://techwriting.miningco.com/
  A huge resource of links and articles relating to technical writing.
• http://www.writerswrite.com/technical/
  More resources and articles relating to technical writing.
• http://www.smartbiz.com/sbs/arts/bly10.htm
  Good tips on the actual writing.
• http://www.worldwidelinks.net/techwriting/
  More resources, with emphasis on the publishing side.

Specialist agencies for technical authors:

• http://www.kudos.co.uk
• http://www.digitext.co.uk
• http://www.tmstoday.com

About the Author
Karl Sinfield is a graduate of Physics and Astronomy from Sheffield University. After graduating, he studied English Literature and worked at a Jesuit private school teaching astronomy to 14 year olds. He then, via the Kudos agency and some good luck, landed a job as a junior technical writer in London. Over two years and under the tutelage of two great senior technical authors, he solely wrote three manuals of a 21 manual suite and contributed to the maintenance of many others, as well as co-ordinating the external printing of the final bound texts. He also help implement a large online help system, contributing graphical as well as written material within a team of six authors. When the company was sold and the team broken up, he retrained himself in graphic design and HTML, and this is his role today.