What do (we) Technical Writers do?

Technical Writing Aug 21, 2008

When you get pre-written (“off the shelf”) software programs you usually get some sort of manual or user guide. It may be a printed book, PDF file, remote web site, local web site,  Help file….whatever. 

If you have software written for you – known as being developed – then the manuals etc must be created as well.  The usual steps in the big cycle are roughly:

  1. Get Requirements (what does this software have to do and how will it do it?)
  2. Design the solution
  3. Develop the programs and related stuff like screens and data storage
  4. Test that 3) is meeting 1)
  5. Write up the documentation on how to use the solution, plus how to manage it and even how to trouble-shoot it.

4 and 5 can be done at the same time. In fact 3 and 5 can also be done at the same time, with a bit of care.

And what I do is the 5: write things up. Usually into Microsoft Word documents – which finally end up as PDFs in most cases (so people cant modify them, even accidentally)

The usual documents are, as implied above:

User Guides: for the end-user with their browser screen. The day-to-day usage. How (exactly) do we perform Task A and Task B with this software. Will involve step-by-step instructions with associated images/pictures of screens (screen captures). Plus background information, warnings, notes etc.

Administration Guides: for the ‘back office’ side of things. How is this software set up; adding users, configuring the servers and networks, changing configuration files, security, backing things up etc.  Probably more ‘technical’ and less need for step-by-step stuff.

Trouble-Shooting Guides: close cousins of Admin Guides. Exact steps on what to do if a specific problem arises.

Of course some sites just need one of the above, others want all 3, but merged into the one super guide. There may also be Product Overviews and Training Material (usually PowerPoints) thrown in as well.

Other types include documenting hardware, software and networking a customer has; their inventory has just built up over the years and there’s no Big List of everything nor how it all hangs together. Or re-writing/editing their existing documents.  Or – in some cases – coming in well after the software is finished and then starting writing up how it works or documenting the internal design.

This is one side – or type – of Technical Writing in the computer world. It’s the one that I do; having 25 years of hands-on technical experience.

Another side is more business focused. Looking at – and documenting – more of the ‘human side’ processes: “If a phone call with a complaint comes in and the team leader of that product isn’t available, then we….”   Lots of flow charts!   And that sort of stuff isn’t for me.

Or as I say; I’m a TECHNICAL Writer….

Tags