Technical Writing for the Terrified
Technical writing manuals: Do you need to hire an expert?
by: Mike Kemp
Sometimes it may be beyond a companies or individuals budget to hire a professional writer to address their technical documentation. Although in an ideal world all technical writing manuals should be produced by a highly trained expert, unfortunately we do not live in an ideal.
In the same way that many people will attempt to repair their own home appliances, some people believe they can do the technical writer jobs and write quality technical documents without all the information they need to do it. Just as fiddling with a toaster can result in electrocution, attempting to write technical documents from scratch without prior advice will ultimately result in failure.
As a rough rule of thumb you should always seek to employ a specialist, but if for whatever reason you can't and you are the poor unfortunate that has had documentation duties foisted on them, don't despair. This brief guide outlines some of the core skills you will need to bring to your writing, technical conventions to be aware of, software packages you can consider, and definite things to avoid.
Hopefully even if you
have never written a sentence in your life about anything vaguely
technical you will have at the very least, a broader picture of what
technical writing jobs entail.
Technical writing unsurprisingly enough, refers to writing that is technical in nature. Although this may seem like a fallacious definition, it's an important one to remember.
Too many technical authors make the mistake of creating documentation that is either too technical, or too 'literary'. A good technical author should be able to adjust the balance between the two to suit the end user of the documentation.
Technical writing manuals are a lot like fresh air, pervasive and yet pretty much invisible. In the weird wired world in which we find ourselves, technical writing and technical writing jobs are everywhere. Software manuals, user guides for home appliances, instructional leaflets, emails, letters, reports, technical news reports, statistics and biographies on television sports shows all are examples of technical writing to which people are exposed to on a daily basis.
If you have ever tried to program the time settings on a home video recorder and flung the manual across the room in disgust, you threw a piece of technical writing (although obviously not a very good one!). Too many times technical literature is produced by writers with not a large enough grasp of technology, or technologists that lack an ability to write.
As a prospective technical author you must tread the
very delicate line of being technically knowledgeable in your specialist
field(s) as well as being a 'good' writer (as opposed to 'bad' writers
who can usually be found mugging sweet old ladies or something).
Technical documentation is usually produced for two distinct user
groups, namely expert level users, and naive users. As a technical
author one of your first tasks is to sort out what audience you are
writing for, which brings me deftly to:
As the old cliché goes, everyone's a critic. This is particularly true of most sane people's reaction when faced with technical writing.
As was highlighted in the technical writing examples of the video recorder above, technical writing can be impenetrable to the end user. If this is the case, it is because whoever wrote the documentation, didn't bother to identify their audience and write to their level. It seems an obvious point to make, but one that is often overlooked, that the user of the documents your are creating, may not actually be an expert.
Obviously if you are creating a document on a particular specialist product for a particular advanced user group (a good example could be auditing software for computer system administrators) then you will need to compose this is an entirely different way than if you are creating for example, technical writing manuals for mass market computer software aimed at the inexperienced home user.
One of the first tasks you must accomplish before you even put pen to paper, of finger to keyboard, is to identify who the user of your technical writing manuals or documents will be and construct documents aimed at that particular target group(s).If you get this stage correct, it should avoid your documents being thrown across rooms in annoyance!
Once you have identified the target market for the technical writing manuals you will be creating, you will need to start to plan how the documents will be organized. This process is largely dependent on what documentation is being produced, but you can follow a few rough rules of thumb and follow these technical writing tips.
Firstly, if the documents are to support a particularly detailed product (such as a computer application) get your grubby hands on it as quickly as you can. By examining the product in detail you can formulate a plan of attack and begin to compose an organizational structure. Whilst you are exploring the product in detail, take copious notes, as doing this during the initial exploratory stages can save you time which can be absolutely vital if you are working to deadline.
Even at the planning stage you must ensure there is a consistency to layout, and organizational structure for the document. Select numbering conventions, paragraph styles, and generate rough ideas for layout purposes now, and save vital time later.
Before diving headfirst into creating the documentation, draft out each section first. This will allow you to reorder if the documents being created do not have a logical 'flow' without seriously having impact on the project.
Many technical documents (especially for more detailed products) are made up of numerous (and in some cases practically countless) iterations. This is because the product shifts and changes over time, and one of the principal duties of a technical author is to keep abreast of these changes, and to ensure that they are all well documented.
Good technical writers will always push their technical writing
manuals and documents through as many drafts as humanly possible,
refining on each draft, until they reach a position whereby they (and
their employer) is satisfied that the documentation is timely, accurate and a true reflection of the product or process it documents.
As already identified, technical writing is called that because it is technical in nature. Part of being technical is to be precise, and part of precision is to be as detailed as humanly possible.
Even if the documents you are creating are for an advanced and technologically sophisticated user group, your documentation must focus on the details of a process, or in using a product. This can be a difficult feat to accomplish, but not if you write to your audience.
Never assume that the reader knows anything about the product or process be documented, but in the case of advanced / expert users at least have the common sense to recognize the fact that they probably do not need to be told how to use the equipment they operate on a daily basis.
When describing how to carry out a particular activity or task, identify each stage involved (number them if this fits the conventions of the document type you are creating) and to ensure the accuracy of what you have written test it yourself, or even better, rope in a volunteer of the same skills level as the end user.
Then, and only then, will you know that your technical writing manuals are correct.
Although it is possible to create technical writing manuals and documents using parchment and blood, it's not advisable. Many specialist software applications exist to help you create powerful documentation, and part of your duties as a technical author, include selecting the right tool for the job.
Largely this depends on the nature of the documents being produced, and the nature of their eventual distribution. If the documents can be delivered using the Internet, this is certainly an avenue to consider. To that end make use of packages such as Flash MX and Dreamweaver to achieve this goal. For integrated online help, you may wish to create raw HTML documents, or alternatively select a specialist package such as RoboHelp or similar.
In the case of print based documents, you will need to select a software package powerful enough to handle what you will throw at it. Many inexperienced technical authors instantly turn towards Microsoft Word (as it is ubiquitous in may commercial and private environments). Unless your documentation is going to be beneath 150 pages, and you know how to create templates and make macros, avoid MS Word. As any technical author will tell you it has nasty habits all it's own, and can often be an unstable package to work with.
you are creating graphics heavy documentation, you may wish to consider
some good software.
Whatever software you select, you must ensure you become incredibly
proficient with it, either by investing in training, or by using it day
after day after day!
Many people will tell you that creating technical writing manuals and documents is tedious and repetitive. These people, are wrong. Although you may find the process of creating technical documentation 'boring' (if you do you are in the wrong job!) it isn't.
Creating quality technical documents is a vital stage in allowing people to adequately and correctly use technology. Although no user will approach the documentation you create in the same way as they approach a novel, you can ultimately help them achieve what they want to achieve using technology and technical writing manuals.
No matter how 'dull' the process may appear to be, allowing users to achieve their goals by reading your technical writing manuals should give you a rush of pride and indeed, happiness. As long as you remember the positive effects that technology can have on people's lives, when you create your documents you can communicate more effectively, as you will be happier in the communicative process. Technical writing manuals is an important job, people need you.
Throughout the documentation life cycle, you should seek to liaise with colleagues as often as possible (if applicable). Let them read your documents, listen to their criticisms, and adjust your documents (if you can't argue your corner!).
A technical writer is paid to communicate, make sure that you do, and never forget why your are communicating, and to whom, in the documents themselves. Write clear technical writing manuals and you will have a long, lucrative career and of course, make money writing.Opportunites in Technical Writing
When creating technical documents there are a number of fatal flaws you can make. Although by no means exhaustive, this section details some of the more common mistakes new authors make in producing technical writing manuals, in the hopes that you will avoid making them too:
Writing for the Technical Professions
Writing technical writing manuals is not, regardless of what you may think, an easy job. It requires expertise, patience and a very odd mixture of skills.
Just like any other job, you can learn how to do it, but even that tuition will not necessarily make you any good at it. To be a good technical writer, you have to be anal yet creative, focused yet communicative, and a flexible expert. This, as you can probably imagine, is no simple task.
Although you may think creating technical
writing manuals is easy, creating accurate, consistent and timely
documentation to a high commercial standard is a highly challenging
role. Regardless of your budget, in the long run it will provide
significant ROI if you hire a specialist. After all, they will be able
to do in days, what you tear your hair our attempting to accomplish in
weeks if not months.
About The Author
Over the years Mike Kemp has been employed as a freelance IT journalist (working for publications such as The Register, Namesfacesplaces, Security Focus and Packet-storm), a copywriter, video-games designer, security auditor, web designer, graphic designer and IT trainer.
He has worked in a variety of freelance and permanent positions for both small (e.g. two men and a dog) companies to multinational organizations throughout both the UK and Europe.
When not working on various articles, books, manuals, and assorted other copy for clients, Mike can usually be found toiling on a variety of unpublished novels. He has had several of his short screenplays produced by independent production companies, and is currently working on several feature length scripts.
"A cardinal rule of writing to follow is, never write your own back cover copy. Why? You’re too close to the work and can’t be objective. Enter Maria Pease.
I contracted her services to write the back cover copy for my upcoming novel, Crossing Lives. The only caveat was, my manuscript was nowhere near finished. Despite this obstacle, Maria took on the project.
Most copywriters won’t touch this type of project unless you can furnish them with a copy of the entire work to be summarized.
In a span of three weeks, with just a few chapters and handful of character sketches to go by, she was able to craft a masterful blurb that captured the essence of the story I’m trying to tell.
Maria communicated with me on consistent basis and took a personal interest in my project. This was a pleasant surprise. Most “work for hire” is cold, aloof, and distant.
I highly recommend Maria Pease for all your copy writing needs."
Matt Leatherwood, Jr. Author, Train To Baghdad http://youtu.be/4ENnNDy-Thc
“Thank you very much for the job well done! I hope we will have an opportunity to work together again in the future."
Timo Kestrel - Website Owner UK
"I needed a website for my new practice and I had no time or skills to do it myself. Thank goodness I met Maria through a business associate. She had my site up and running in no time. She even gave me some suggestions on how to make some affiliate income along with the service I provide.
If you need a writer who listens to what you want and gives great ideas on how to improve it, call Maria. You won't be disappointed."
Sandee West - Marriage & Family Therapist
"Maria has developed a business brochure and numerous newsletters and has been able to interpret the information I give her into professional writing pieces that communicate to my clients the value of my product.
Maria’s professional knowledge has played a large part in portraying my company in a professional light.
Maria Pease has been a pleasure to work with and I feel she would be an asset to any company in need of a commercial writer."
Lisa Beach - The Box Wrap Company
"I needed to update most of our marketing and sales materials including a brochure, a couple of sales letters, tips sheets and some in-house communications. Maria took care of it all and did a beautiful job on all of it. If you are looking for a capable, and enjoyable copywriter to work with, you can stop looking, Maria is your girl."
Wayne Francis - Window and door installation services
"I hired Maria Pease to help me promote my business and have been extremely pleased with her performance. She has developed all of my marketing materials to date including brochures, postcards, and promotional flyers.
Maria is a pleasure to work with, always energetic and enthusiastic about the task at hand. She continues to come up with fresh, new, innovative ideas to help move my business forward. She is dedicated to providing a superior product and has continued to exceed all of my expectations. It has been refreshing to me, as a small business owner, to be able to rely on an outside consultant to be professional, reliable, and self motivated."
Andrea Tomes - New Image Fitness
"My advice is to hire Maria Pease to write for you. She is full of great ideas and will execute them beautifully. I have worked with her many times on several different types of projects from articles to websites and more and she never disappoints. She is truly a delight to work with. If you need a writer, look no further than Maria."
Ken S. - Business Owner
Read Chapter 1 Here.
Writing E-books for Fun and Profit explains step by step how to get ideas for your ebooks as well as how to write, publish and market your ebooks.
Also included is writing advice and checklists, links to writing, publishing and book promotion websites are included to assist the reader to stay on task when creating their own ebooks.
Revised and updated.
Do you love to learn new things, just for the sake of learning? Do you enjoy sharing what you learn with others? Do you enjoy the written word? Can you clearly describe the steps needed to get something done?
If you answered “yes” to these questions then you may just be the perfect candidate for making your living writing “How To” information!