Deprecated: mysql_connect(): The mysql extension is deprecated and will be removed in the future: use mysqli or PDO instead in /home/a26f9f83/public_html/articles/includes/config.php on line 159
Technical Writing for the Terrified > NetSparsh - Viral Content you Love & Share

Technical Writing for the Terrified

Introduction

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 documentation 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, many people will attempt to write quality technical documents. 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 entails.

What is Technical Writing?

Technical writing unsurprisingly enough, refers to writing that is technical. 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 is a lot like fresh air, pervasive and yet pretty much invisible. In the weird wired world in which we find ourselves, technical writing is 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:

Know thy foe

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 example 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, a technical manual 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 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!

Planning for perfection

Once you have identified the target market for the documents you will be creating, you will need to start to plan how the documents will be organised. This process is largely dependent on what documentation is being produced, but you can follow a few rough rules of thumb. 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 organisational 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 organisational structure for the document. Select numbering conventions, paragraph styles, and generate rough ideas for layout purposes now, and save vital time later.

Let a Draft in

Before diving headfirst into creating the documentation, draft out each section first. This will allow 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 authors will always push their 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.

The devil is in the detail

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

Choose the right tool for the job

Although it is possible to create technical 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. If you are creating graphics heavy documentation, you may wish to consider Quark Xpress, or choose potentially the industry leader in the field, Adobe Framemaker. 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!

Communicate - that's what you are paid to do!

Many people will tell you that creating technical documentation is tedious and repetitive. These people, are wrong, and possibly morons too. 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. No matter how 'dull' the process may appear to be, allowing users to achieve their goals by reading your documents 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. 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 author is paid to communicate, make sure that you do, and never forget why your are communicating, and to whom, in the documents themselves.

Common Mistakes to avoid making

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 the hopes that you will avoid making them too:

Being Patronising - Although technical documentation should be clear, it should never be patronising. You are not creating documents to be read by morons but consumers and clients. You should always write to the skills level of your audience, but no matter what technical level people are on, they are not morons. Even children get offended when patronised, don't make that mistake with someone who is paying your salary, child or otherwise.

Overuse of humour - People do not read technical documents to be entertained, they read them in the hopes of successfully completing a process, or extracting information. Unless it is relevant to the end user, avoid humour wherever possible. If you are writing a book, fine and good. If you are writing a manual, avoid humour like the plague, as more often than not users will miss the joke and just end up loathing the patronising idiot that wrote the documentation.

Inconsistency - Even at the drafting stage, you should ensure that all the elements used in your document are consistent. This applies as much to the 'tone' of the document as to the layout of it. Ensure you use consistent senses (first person, etc.) as well as page layout, pagination elements, headers and footers, and all other textual elements.

Proof read - By the end of creating a piece of technical documentation, you will probably be sick of the sight of it. That doesn't matter. What matters is what leaves your office or home, is accurate. To that end proof read the document throughout all it's drafts, and before it is distributed proof read it again, and again, and again. Never rely on spell checkers (they never work) and if you can avoid it, never rely solely on your own judgement. Get your document read by as many pairs of eyes as possible prior to distribution, after all, they could spot the one thing you have been missing throughout the creation process.

Conclusion / Shameless self promotion

Technical writing 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 author, you have to be anal yet creative, focussed yet communicative, and a flexible expert. This, as you can probably imagine, is no simple task. Although you may think creating technical documents 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 Packetstorm), a copywriter, videogames 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 organisations 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.

Mike lives mostly happily in a dreadfully un-bohemian London suburb with his long-term (and long-suffering) partner, and two addled cats. To learn more about Mike, the range of projects he has been involved in, and other assorted stuff and nonsense, please visit his personal homepage at www.clappymonkey.com.

In The News:

This RSS feed URL is deprecated, please update. New URLs can be found in the footers at https://news.google.com/news

UNCW News

Writing the Book: Annual Writers' Week Celebrates Guest Authors of Ecotone Essay Collection
UNCW News
2) is organized around the launch of Trespass: Ecotone Essayists Beyond the Boundaries of Place, Identity, and Feminism, an essay collection forthcoming from the creative writing department's award-winning national literary magazine Ecotone, and ...


Washington Post

As Trump administration eyes writing transgender people 'out of existence,' a reckoning for a transgender Republican
Washington Post
Jordan Evans, 27, is a town constable and an elected library trustee in Charlton, Mass. She's a Republican, as are most of the people in her hometown, a rural community where about 54 percent of voters cast their ballots for Donald Trump in 2016. Evans ...
'Transgender' Could Be Defined Out of Existence Under Trump AdministrationNew York Times
Donald Trump to LGBT community: I'm a 'real friend'CNN
Trump Memo Disqualifies Certain Transgender People From Military ServiceNPR

all 600 news articles »

Washington Post

Writing the racy 'Mr. Nice Guy' was a family affair
Washington Post
Jason Feifer and Jennifer Miller published books before and after they met in 2009 on OkCupid. The 38-year-old authors married in 2011 — but it took a lot longer for them to really take the plunge and enter into a writing relationship. Their first ...
Book World: Writing the racy 'Mr. Nice Guy' was a family affairAlton Telegraph

all 2 news articles »

Murakami enjoys writing because he doesn't know the ending
Minneapolis Star Tribune
TOKYO — Haruki Murakami says he enjoys writing novels because he doesn't know how they'll end. The Japanese author behind global best-sellers like his latest, "Killing Commendatore" hosted a special radio show on Sunday. He said he starts writing ...

and more »

bgfalconmedia.com

Youth learn to love writing at library's writing fest
bgfalconmedia.com
Children and adults alike in the Bowling Green area got to show their love for writing in a new event for the town. The Wood County District Public Library hosted a writing festival over the weekend in honor of the National Day on Writing. The day was ...


BBC News

The one writing skill you must master
BBC News
We live in a digital age that likes to pretend that writing is speech. We tap out emails, texts and update our social media profiles in the places – busy commuter trains, cafes and streets – where we also talk. We write as if we were talking. This kind ...


Atlas Obscura

How Writers Map Their Imaginary Worlds
Atlas Obscura
One of life's great treats, for a lover of books (especially fantasy books), is to open a cover to find a map secreted inside and filled with the details of a land about to be discovered. A writer's map hints at a fully imagined world, and at the ...


Bustle

9 Easy National Novel Writing Month Prep Tools For People Who Write "By The Seat Of Their Pants"
Bustle
NaNoWriMo is right around the corner, and if you feel woefully under-prepared — or if you're just the type of writer who doesn't prepare much at all — you might be tempted to skip out on all the fun this year. Don't worry! I've got nine easy ...

and more »

Creative Loafing Tampa

A complete list of Tampa Bay's November National Novel Writing Month groups
Creative Loafing Tampa
To the uninitiated, NaNoWriMo is an annual event that started when San Francisco freelance writer Chris Baty convinced 20 fellow writers to commit to writing 50,000 words in one month. This year, nearly a half million people worldwide will attempt to ...


Chicago Sun-Times

Parking ticket writing stabilizes; vehicles getting booted drops by 10.5 percent
Chicago Sun-Times
The ward where the greatest number of parking tickets were written was the downtown's 42nd. But, even though parking ticket writing was the same as last year citywide, it increased by a whopping 29.5 percent or 34,791 tickets in the 42nd Ward. The ward ...

Google News

Have You Tested Your Plot?

Creative Writing Tips ?Our plotting stage is our testing area.Everything... Read More

Freelance Writing: A Career From Anywhere

An island in the Mediterranean. A beach in Africa. The... Read More

Go With The Flow: Write With Transition Words and Phrases

One of the most common weaknesses I see in day-to-day... Read More

Is The Theme Reinforced In The Ending?

Creative Writing Tips ?By now you should have an idea... Read More

The Untold Secrets of Writing Best Selling Childrens Books

Ever wondered how the most successful children's book writers get... Read More

Suspense Novels Made Easy

Suspense novels are probably the easiest novels to write. Suspense... Read More

Whats Missing in your Nearly Finished Book?

Bookcoaching clients come to me at different stages of writing... Read More

How To Break Into Print Publishing

The big question. Do you submit directly to the publishers,... Read More

Realize Your Book Dream In 2005!

If you haven't realized the success you wanted last year,... Read More

How to Build Your Site with Other Peoples Content -- Part 1

Building a new website can be extremely exciting. Seeing your... Read More

Editing Secrets

Once you've plotted out your book, developed the characters and... Read More

A Few Brief Tips to Deal with Writing Rejection

What to do when you get rejected.You've just finished your... Read More

On Writing and Poetry: Harry Calhoun in Conversation

"This is just brilliant. The whole interview is incredible? I'm?... Read More

Publish It Now! No Matter What It Is

Do you want to publish something? An article, a non-fiction... Read More

7 Weapons to Conquer the Giant Procrastination Keeping You from Your Book Dream

Have you been guilty of procrastinating on your book project,... Read More

A Quick Guide to ISBNs for Self-Publishers

ISBN stands for International Standard Book Number. It is a... Read More

Writing Secrets You Must Know

Writing better is critical for students. But it's even more... Read More

6 Ways to Leverage Technical Articles

Technology vendors often contribute bylined articles to trade journals. The... Read More

Need a Book Coach, Ghost Writer, or Editor? Part 2

If you either want to write a book to help... Read More

Suspense Novels Need Fast Starts

Suspense novels, unlike any other genre, need fast starts. Fans... Read More

Help! I Cant Write!

Writer's Block can strike like a King Cobra, paralyzing every... Read More

How To Filter Description Through Your Characters

How do you describe a scene without slowing down the... Read More

How You Can Find Freelance Editing Jobs

Freelance editing opportunities are out there, you just need to... Read More

Writing Technique: The Restaurant Syndrome

Picture this scene.Your hero is sitting in a bar. He's... Read More

Crime Writing Beckons

If your cash is running out fast and you have... Read More