Introduction to Technical Writing | Technical Writing Tutorial

technical writing

© Ugur Akinci

Table of Contents

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 1

What is technical writing?

“Technical Writing” is a writing niche specialized in EXPLAINING how things work, and TRAINING others in how to perform specific TASKS to accomplish selected GOALS or tasks.

Important concepts here are:

* Explaining
* Training & tutoring
* Tasks and performance goals

Let’s take a step back and look at the LARGER PICTURE of writing in general…

There are 5 different types of writing in general, each overlapping in different degrees:

1. Creative writing (GOAL is to move people emotionally)
2. Commercial copy writing (GOAL is to sell things to people)
3. Business writing (GOAL is to administer people efficiently)
4. Scientific writing (GOAL is to record and share scientific findings within academia)
5. Technical writing (GOAL is to explain how things work and how people can perform specific tasks)

Do you now have a better idea of where technical writing stands with respect to other types of writing?

+++++++++++++++++++++++++++

Lesson 2

A typical day at the office for a technical writer…

Sometimes people who are considering technical writing as a career ask me what a typical day in the life of a technical writer looks like.

“What is the daily routine for a technical writer?” they ask.

I for example work for a software company and here is what I do in a typical day, in a typical year

I write user manuals, system administration guides, installation guides, quick reference guides, release notes, help files… depending on the day.

Perhaps I should also mention that, while writing these products I also consult with various Subject Matter Experts (SMEs), sometimes through e-mail and other times on the phone or through teleconferences. In some years I even travel out-of-state to meet with those SMEs who work in far away offices.

Some technical writers working for software companies help with testing the product as well by both working as a tester and also by writing the scenarios that the testers use.

I also draw diagrams and illustrations to illustrate some of the guides I write.

There are a number of administrative tasks that I take care of as well, like attending the departmental meetings, filling in time sheets, etc.

And of course around noon time there’s usually a half-hour lunch break. On days when I’m swamped with work I just skip it, or push it to late afternoon.

No two days are alike when you’re a technical writer working out there in the real world. It’s an exciting career full of interesting challenges and plenty of room to grow into with new skills while making a good living at it too.

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 3

Difference Between Business Writing and Technical Writing

There are a number of books, programs, and classes out there today offering to teach “technical writing.”

Some of these are excellent; prepared by industry veterans who know what they’re doing.

But some others are basically rehashing the traditional “business writing” concepts and techniques under the guise of “technical writing.”

“So what?” you may ask, which is a fair question.

And here is the answer: if you are seriously considering to go out there and find yourself a job as a “technical writer” then you need to have at least one technical document prepared according to industry standards and expectations.

Business writing in general will of course help you communicate better and conduct your business more efficiently. That’s why it’s a good thing. But when it comes to finding a technical writing job, traditional business writing won’t help you much. No recruiter will accept a business writing sample as a proof of your technical writing skills, especially in the hi-tech sector where I’ve been working for over 10 years now.

Business writing is all kinds of copy generated to administer, communicate with and control others in a work environment. It covers all office communications, and topics like how to write a memo; how to write an e-mail; how to prepare a report; how to write meeting minutes; all kinds of business letters, etc.

While helpful, such knowledge will not be enough to find a job in the highly competitive field of modern technical communications.

Instead, what you need to learn is the kind of documentation generated every day in such hi-tech industries as software, hardware, networking, telecommunications, manufacturing, chemicals, finance, defense, etc. You need to learn how to write and format user manuals, system administration manuals, configuration and installations guides, release notes, help files, etc. The list is a very long one indeed…

Does your instructor help you learn what a “scope” document is, for example, and how it should be written? How do you prepare and write “release notes”“? What’s the crucial difference between a “Functional Manual” and a “Procedural Guide”“? How would you write a QCP for a defense contractor?

There are many other similar topics that beginners need to learn to prepare themselves for a great career in technical writing. Once you know the crucial difference between “business writing” and “technical writing,” you can make a better decision as to which questions to ask before buying a technical writing book or registering in a technical writing program. That way you won’t waste your time, money and energy on a product or a program that won’t help you reach your main goal. As always the case, knowledge is power in this particular issue as well.

+++++++++++++++++++++++++++

Lesson 4

Difference Between Copy Writing and Technical Writing

Copy writing tries to sell products and services, as the advertisement-legend David Ogilvie always (and rightfully) maintained. And I agree with him. Until and unless someone buys something, copy writing is not good for anything.

Technical writing, on the other hand, is an answer to the basic question of HOW.

But in order for technical writing to explain the “how” of anything, there first has to be a clear definition of its “WHAT” and “WHY”. Without that pre-requisite step, your technical writing can easily get lost in the woods.

This is usually expressed as the principle of knowing who “the audience” is.

This is just another way of saying that unless a technical writer is sure of the PURPOSE behind the document, that is, the manner in which the users will use the document to PERFORM certain tasks, then just explaining how something is done, may or may not get the job done.

Why?

Because there is always more than one way to describe the HOW of anything.

For example, imagine you are asked to write a technical guide on the HOW of running; a “User’s Guide to Running.”

If as a technical writer you immediately pull up your sleeves and start writing i, you might be in for a big trouble.

Let’s say you devote chapters on strength and speed training, without ever thinking WHAT this guide is supposed to achieve, for WHAT kind of an audience.

What if it turns out that you were actually asked to write this guide for runners over 50 years old, who could care less about “strength” and “speed” but are keen about “losing weight”? That of course would require a totally different sort of technical guide, wouldn’t it?

Copy writing excels as long as people buy the product; period. The late copy writing geninus David Ogilvy stated that fact half a century ago and nothing has changed since then.

Technical writing, on the other hand, excels only when the description of HOW matches the PERFORMANCE GOAL of the project’s AUDIENCE (or, the project’s “WHAT” and “WHY”).

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 5

Types of Technical Writing

Technical writing is a vast field. Here are some different types, organized by different ways of looking at it.

By industry category:

Technical writers are employed by the following industries (an incomplete list by its very nature…):

* Software + Hardware +Networking
* Financing + Investment +Banking
* Education + Academia
* Governments at all levels
* Manufacturing plants
* Phamaceuticals + Medical equipment
* Sports
* Gambling + Entertainment
* Transportation companies
* Communications + Broadcasting
* Press + Publishing
* Telecommunications
* Security Access + Protection
* Health
* Sports + Personal Training
* Tourism
* Politics + Law
* etc.

In short, technical writers work in every industry and in every field. You would be hard pressed to find a single industry where technical writers are not employed.

By employment type:

Technical writers are:

* Self-employed freelancers
* Employment agency employed independent contractors
* Payroll employees

Each has its own advantages and disadvantages. We’ll pick up this topic again later on.

By skill level:

There are basically two types skill levels involved in technical writing:

* Business-writing skills. This level overlaps considerably with business and commercial copy writing and involves writing business letters, grants, proposals, press releases, etc.
* Hi-tech skills. This level requires specialized technical knowledge of electronics, pharmaceuticals, finance, telecommunications industry and generates documents catering to the insiders or the consumers of that industry.

+++++++++++++++++++++++++++

Lesson 6

Three sources of employment for technical writers

There are three ways to get a job as a technical writer:

1) On your own, as an independent freelancer.

2) Through a job agency, as an independent contractor.

3) As a company employee.

Each offers different benefits and advantages, depending on your skills as a technical writer, your background and your personality.

——————————————————–

1) To be on your own is perhaps the ideal of most freelancers and it certainly has its allure. That’s the good old American dream, isn’t it ?

But I wouldn’t recommend going 100% freelancing if you don’t have advanced “social engineering: skills, including heavy-duty networking.

A second point is, yes, freelancers make more money when there’s work to do but their expenses are also much higher. They pay all their (and their family’s) medical insurance, disability and life insurance (if any), Social Security and FICA contributions (for U.S. workers), etc.

2) Job agencies fit you into the projects they secure from the companies where you actually do the work. In a way, they lend you to this other company for a fee. They take their share from the top and pass on to you the rest. If you are good at what you do job agencies can be a steady and lucrative source of income.

I worked briefly for Fannie Mae back in 2006 through a similar agency and I liked the experience very much.

However, if you do not like your job, the agency might not have another and better one for you in waiting. So there is a danger of getting stuck with assignments that you don’t like.

There are many employment agencies that you can query as a technical writer. Just search for them on the Internet with the key words “technical writing jobs” and “technical communicator jobs”.

As to the benefits, most major agencies cover your medical insurance and other side benefits for a fee. The amount you end up paying is less than what you’d pay as an independent freelancer but more than what you’d pay as a full-time employee.

3) Working directly as an employee for a company is the best in terms of long-term job security, on-the job training opportunities, paid annual vacations, medical-dental-vision coverage, and a variety of other side benefits.

I highly recommend this alternative since it usually comes with generous 401(k) retirement plans and even (which is rare these days) an additional pension plan. During my technical writing career I have worked for 10 years as an employee for major Fortune 500 corporations and I never regretted it.

Good luck with your job search and let me know if you have any questions.

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 7

7 low-tech technical writing jobs that pay well

You do not need to be a computer engineer or a scientist with Ph.D. to become a top-notch technical writer. There are many low-tech writing niches that you can prosper in even if you are not too comfortable with hi-tech subject matters. Here are seven such opportunities available to all technical writers:

1) Grant Proposal writing. There are a lot of non-profit organizations out there looking for writers to prepare and submit a grant proposal on their behalf. The same goes for for-profit corporations that need writers to prepare the necessary documentation to satisfy the conditions stated in a RFP (Request For Proposal) document and win commercial bids.

2) Resume and cover letter writing. Resumes and cover letters are “evergreen” writing gigs since they are needed all the time. But especially in times of economic hardship and recession, a good resume becomes more important than ever. Learn how to write great resumes and cover letters and you’ll never be without a job.

3) Quality Control Plan (QCP) writing. This is a document submitted by a defense contractor trying to win a defense-related bid. You can learn how to write one within a day and make good money freelancing for defense vendors and contractors.

4) Tests and Quizzes. There are many tutoring companies, SAT and other exam-prep book publishers who need technical writers come up with all kinds of exam questions, tests and quizzes. Pick up one such book you like, find its publisher, and send a query to the editor.

5) Policy and Procedure writing. Policy and Procedure manuals are needed by all kinds of civic, religious, and military organizations, corporate Human Resources departments, and non-profits in general. You gather and compile the rules, policies and procedures so the managers know what to do when something goes wrong.

6) Case studies. A case study defines a problem for an organization, describes the alternative methods tried to resolve the issue, and then defines one solution that worked the best, with Before and After figures. Many mid- and large-size organizations have such case studies written both for their internal training and marketing purposes. This is a lucrative field that overlaps with writing White Papers.

7) Game rule writing. Video and board games is a $12 billion industry and growing. Every game must have its own file or booklet of rules and technical writers write them. If you can write clear directions on how to play a game, what constitutes a “win” or a “loss,” what are the things that are allowed and not allowed, and express it in a language that can be understood by an average reader with only high school education, you might have a job with a game company.

+++++++++++++++++++++++++++

Lesson 8

4 hi-tech technical writing jobs that pay well

Some technical writing jobs require that you have a science background or that you are familiar with finance and banking terminology and know how the financial markets work. Here are four such well-paying writing opportunities for technical communicators with a college background.

1) Defense industry writing. Due to the recent political developments and wars, defense expenditures have went through the roof within the last decade. And all defense companies need technical writers, some with top-secret security clearances, to document their products and services. If you specialize in this niche, you won’t have too much difficulty in finding and holding a full-time writing job with good pay.

2) Financial writing. Even when the global financial markets collapse, there is still a great need to explain to the average taxpayers how to invest or not to invest their money, how to save, which alternative money management methods they should adopt, how to set up their retirement accounts and insurance plans, which financial products they should purchase and which ones they should avoid. And those are all information tasks that are handled by technical writers. If you combine your finance knowledge with copy writing skills and get into the highly-competitive Financial Newsletter writing niche, your income may rise even more rapidly.

3) Medical and Regulatory writing. This is one writing niche where the employers have more cash than they know what to do with it. Pharmaceutical companies, especially, are always solvent and they regularly need top-notch science-savvy technical writers to generate their regulatory documents. Without securing the approval of regulatory agencies no drugs can be marketed to the general public. Thus the work that medical writers do can be of vital importance for a drug company and that’s why medical writers are among the best paid hi-tech technical writers.

4) Software/Hardware documentation. Software and hardware companies around the world always need technical writers to write their specs, user documentation. configuration and system administration documentation, installation guides, quick reference guides, end-user help files, and dozens of other documents that they need on a regular basis. Related writing niches include telecommunications, network, and security access documentation.

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 9

Pros and cons of technical writing

You should become a technical writer if you like the following:

* A steady writing job, with generally good and above-average employment prospects
* A well-paying job (in 2007, the average American technical writer made about $62K a year).

NOTE: To get a free Special Report “How Much Do Technical Writers Make?” please register with my Tech Writing Tips ezine at https://technicalcommunicationcenter.com

* An interesting and challenging job where you are asked to grasp new technical concepts and explain them to others in a plain language
* Generous package of benefits (for payroll employees) that usually include health, life, disability insurance benefits (which sometimes include eye and dental coverage as well), employer 401(k) contribution, retirement plan (depending on the company), training reimbursement, credit union (depending on the company), etc.
* The real psychic satisfaction of knowing that you are doing something that counts, helping other people live better lives and making our world just a little bit better in a concrete way.

But you should not become a technical writer if the following are important for you:

* Getting a byline and making a name for yourself (usually you will never have your name appear on any of the documents you write and thus nobody will know your name)
* Owning the copyright of what you are writing (usually your employer or client will have full copyrights of everything you’ll be writing)

+++++++++++++++++++++++++++

Lesson 10

2 Basic Types of Technical Documents

There are basically two general types of technical documents:

1. Functional Manual
2. Procedural Guide

A Functional Manual is the kind of entry-level document that explain which “button” does what. I’m sure you have seen many “User Instruction” brochures packed with every gadget you buy. Usually such manuals explain the FUNCTION of user controls, without telling you the BEST WAY to use the product.

A Procedural Guide, on the other hand, is harder to write because it requires not only an intimate knowledge of the product or service in question but also an understanding of WHAT the users are trying to ACHIEVE with it. It requires a knowledge of the PERFORMANCE GOALS that the audience has in mind. It’s the sort of document that goes way beyond a mere description of the buttons, menus and controls of a product.

GUI/Button manuals are ideal for beginning tech writers. But you need to be an experienced tech writer to do a good job with a procedural guide.

Technical Documents” src=”https://technicalcommunicationcenter.comwp-content/uploads/2009/02/180px-digital-clock-alarm.jpg” alt=”2 Types of Technical Documents” width=”180″ height=”135″ /> 2 Types of Technical Documents

For example, let’s say you are documenting a digital alarm clock (public domain photo courtesy of Wikipedia Commons).

A Functional Manual would talk about the functions of all the 6 buttons that you see on top this clock. It will tell you how the clock will behave when you click or push them, etc. It will describe the ACTION (e.g., clicking) and its EFFECT (e.g., the numbers blinking). It would establish a CAUSE and EFFECT relationship between the user actions and the behavior of the clock. But we would still have no idea the best way to use this gadget, although admittedly, it’s not that complicated a gadget to use of course.

However, let’s assume that this digital clock has the Bluetooth ability to download the music file of your choice from the Internet and play it when the alarm goes off… Then you would need to write a Procedural Guide explaining the best way to configure this digital clock so that it would perform such a complicated task. That would usually be a series of NUMBERED STEPS describing each step of the PROCEDURE involved.

For example, it might be a procedural description such as the following (provided here just for illustration purposes):

To set your Internet Wake-Up function:

1) Press Button A to display the music type options (jazz, classical, pop, country).

[REMEMBER: You’ve already explained what each button is and does, either in a separate Functional Manual or in the “Operations” or a similar chapter of your “User Guide.” When the readers reach this section they should already have a good idea about “which button does what.” Here we are describing more complex PROCEDURES the user can follow to accomplish more complicated goals.]

2) Press button A and B together to select a music style.

3) Press buttons B and C together to assign the music style to your alarm schedule.

4) Shift the Selection Slide to ON position to save the setting. Now, when the alarm goes off, you’ll wake up with your favorite music style downloaded automatically from the Internet by your alarm clock.

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 11

Characteristics of Good Technical Writing

Here are some of the characteristics of good solid technical writing...

Technical writing needs to be:

CORRECT. This is ultimate. Paramount. No matter what else technical writing is, it cannot be INCORRECT. Period. Everything you write must be ACCURATE and verifiable empirically. That’s why you have to check and double-check all your facts and figures before including them in a technical document.

For example, “World War 2 ended in 1948” is not a correct and accurate statement.

PRECISE. A statement can be correct but NOT precise. Technical writing needs to be both.

For example, “When warmed up, a pot of water eventually starts to boil” is correct but not precise. “When warmed up, a pot of water starts to boil at 100 degrees centigrade” is both correct and precise.

RELEVANT. All statements in a technical document need to be not only correct and precise but relevant as well. Why talk about the history of physics in a Power Boat User’s Manual?

BRIEF. Shorter the better. “To tell the truth, you should ideally not be opening Valve A before you shut down Valve B” is wordy. Cut it down to: “Never open Valve A before you shut down Valve B.” Period.

UNEMOTIONAL. Emotions are great in creative writing and fiction but deadly in technical writing.

“Ignore any stupid error messages from the database server” is totallly unacceptable in a technical document since it is not up to the writer to judge whether a server acts “stupidly” or not. Such a characterization never helps to understand how a system works or how to fix it when it breaks down.

“Ignore any error messages from the database server” is enough.

NON-ANTHROPOMORPHIC. Okay, I admit, I’ve used a “$100 word” but that’s exactly the best word to express this idea. Let me explain…

Sometimes people attribute human-like qualities to non-human components. That’s what “anthromorphism” refers to.

When you write “the client machine loves thin applications,” “love” is a human emotion that a “client machine” actually never feels. Remember our first rule that tech writing needs to be “correct”? A client machine “in love” is simply not correct.

A better and non-anthromorphic statement that says the same thing would be: “A client machine works more efficiently with thin applications.”

+++++++++++++++++++++++++++

Lesson 12

How to Avoid Exaggeration and “Fine Writing”

Technical writing fails when it tries to become “fine writing” or “creative writing.” Why? Because one of the main tools of “fine writing” is attributing human-like qualities to non-human actors and agents. That’s a definite taboo in technical documentation.

For example you commit that error every time you write a sentence like “When the system becomes aware of a user selection, it switches channels.”

“Awareness” is an attribute of organic (human, animal, or perhaps even plant) consciousness. Machines and computer systems are not “aware” of anything the way we humans are aware of things.

A better sentence would be: “When the system detects a user selection, it switches channels.” Here there is no claim that the “system” is “alive” with “consciousness.”

The same “fine writing” error is committed when a technical writer uses adjectives, superlatives, and draws an exaggerated picture of technical states and processes.

For example, in a novel, it may be commensurate with “poetic license” to talk about a “gorgeous pomegranate-colored red pilot light” flashing on and off when the user presses the OFF button. But in a technical document such an exaggerated description comes across a ridiculous.

A better description would be “a red pilot light flashes on and off for 2 seconds when the user presses the OFF button.” It’s simple, correct, and effective.

Again: “When you hear an awful sound coming from the B module, it’s time to change the oil.” The adjective “awful” does not belong in technical writing since it’s meaning is subjective and can change from one person to another. A technical document needs to be as objective as possible to eliminate any variation in application.

A better sentence would be: “When you hear a high-pitched sound coming from the B module, it’s time to change the oil.”

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 13

3 rules of Good English in Technical Writing

Here are three rules that will help you write technical documents that are much easier to read, understand and remember.

1) Follow the subject of the sentence immediately with the verb.

For example: “The operator [SUBJECT], after consulting with her supervisor, normalized [VERB] the database.”

BETTER: “The operator normalized the database after consulting with her supervisor.”

2) Chain-link multiple sentences in a paragraph by ending and starting consecutive sentences with the same topic.

For example: “The new Xenon encrypted servers were installed yesterday after a two month delay. The wrong encryption key was the reason why the installation did not go smoothly. The Project Management, in order to prevent the same issue in the future, decided to implement a new encryption key management system.”

TOPIC 1: Servers installed. Should be at the END of Sentence 1.
TOPIC 2: Installation not going smoothly. Sentence 2 should START with that.
TOPIC 3: Wrong encryption key. Should be at the END of Sentence 2.
TOPIC 4: A new encryption key management system. Sentence 3 should START with that.
TOPIC 5: Preventing the same issue in the future. Should be at the END of Sentence 3.

BETTER: “After a two month delay, the new Xenon encrypted servers were installed yesterday. The installation did not go smoothly due to wrong encryption key. A new encryption key management system will be implemented by the Project Management to prevent the same issue in the future.

3) Consolidate the group of short sentences written about the same topic.

For example: “When there is too much load, network should be shut down. Only an Admin can shut down the network. 10,000 logins per minute is the upper limit of what the network can carry.”

BETTER: “The network, which can carry a maximum load of 10,000 logins a minute, should be shut down by an authorized Admin when that limit is superseded.”

+++++++++++++++++++++++++++

Lesson 14

Why are Templates Necessary in Technical Writing?

Consistency of a technical documentation is what creates that subliminal sense of trust and confidence in the end-users.

A technical document must be “boringly consistent” in order to be trusted.

Just ask yourself: would you trust an airplane maintenance manual that has missing page numbers, has chapter headings printed in different fonts and sizes, has differently formatted figure captions for consecutively printed figures (like “Figure 2-14” on one page, and “FIGURE 15” on next)?

Consistency all starts with a document TEMPLATE. That’s why you need a good template to write a good technical document.

It is harder to shift between different page templates if you are using MS Word as your main text editing program, and much easier if you are using Framemaker or InDesign since the last two are built on the “Master Pages” concept. But a page template is what you definitely must have.

When you have a template, you have consistent margins, sidebars, headers and footers, for starters. You have consistent page numbering and column, and page gutter(s) if you have more than one column.

If your text editor allows you to create Master Pages, I’d recommend you to create a document template starting off with the following 5 types of pages (assuming you are writing a book):

  1. Front Cover
  2. First Page
  3. Right Page
  4. Left Page
  5. Back Cover

And it wouldn’t hurt at all of you design templates (Master Pages) for the following types of special pages as well:

  1. Front Matter
  2. TOC
  3. List of Tables and Figures
  4. Index

Have a template first before structuring your information. It’s a must. “Don’t leave home without it,” as one credit card commercial used to say.

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 15

What’s the Difference Between a “Font” and a “Font Family” ?

A sound knowledge of fonts is a must for any technical writer. In about fifteen or twenty years that may not be as crucial as it is today if and when the technical communication field makes a wholesale shift to “structured authoring” in which the writers may lose control over how their “content” will be formatted and “presented.”

But as these lines are written, we’re still living in the “unstructured authoring” era when technical writers not only gather the content but also decide how that content will appear in print, in a PDF file, on screen, etc. So that’s why they also need to have a good understanding of the fonts and how to use them properly.

First, you should be aware that when we commonly refer to a “font” in daily language we’re usually referring to a “font family.” It is also known as a “font face” or “typeface.”

A “font family” or “typeface” includes all letters of a given alphabet in one or more font sizes, all the punctuation marks, all numbers and a selected set of symbols.

For example, “Helvetica,” “Arial,” “Times Roman” are all font families. And within that “family” there are individual fonts, differing from each other by individual attributes such as “weight,” “style,” “size” etc.

That’s why, technically speaking, “Arial, 12 pt, Italic” is a different font than “Arial, 14 pt, Italic” because they do not have identical attributes (size, in this case). However, they still belong to the same “font family,” regardless of their attributes. This is especially true in print documentation.

However, the introduction of computers did change some of these basic definitions. Since size, weight and style of a font can be changed easily on a computer, the fonts that have different attributes (like weight and size) are referred to these days simply as a “typeface”. For example, “Arial 12 Bold” and “Arial 14 Italic” become “typefaces” in this new on-line design environment.

+++++++++++++++++++++++++++

Lesson 16

How to Use Fonts Properly in a Technical Document

As a technical writer, you should be aware of certain basics about fonts and some basic rules to observe in your documents. The most basic distinction about fonts is whether they have a “serif” or not. That’s why font families are split into two major categories: Serif and Non-Serif fonts.

A serif is a small tail- or wedge-like appendage that extends outward from the end fo a letter or symbol. “Times Roman,” for example, is a famous serif font and “Arial” is an equally famous non-serif font.

RECOMMENDED RULES of font selection for technical writers:

1) Select your headlines from NON-SERIF fonts (like Arial, Helvetica, Verdana, Tahoma, Futura, Optima) and your body text from SERIF fonts (like Roman, Times Roman, Times New Roman, Georgia, Bookman).

2) ITALIC is designed to attract attention to itself by virtue of being hard to read. That’s why, in a block of readable text, it makes sense to emphasize a word or a phrase by printing it in Italic.

However, some authors print whole web or print pages in Italic! That defies the whole purpose of the Italic style. Every time you use Italic font, be aware that you are making your words harder to read. Thus use it sparingly, like using pepper while cooking.

3) Do not use more than two or a MAXIMUM of three typefaces in your technical documents. A profusion of typefaces creates confusion in the reader’s mind. When it comes to fonts, less is always more.

4) Do not assume that all computers have access to every font you have. All computers, however, come with a set of built-in “system fonts” that are installed automatically by the operating system. The most famous of these system fonts are Arial, Times or Times Roman, and Courier (or Courier New). If you use these three fonts you can rest assured that your document will appear in the receiving end in the same fonts that you have used on your machine.

If, however, you use a hard-to-get fancy font, the reader’s machine will substitute the “closest font available” to render your document readable. “Optima” for example may be replace with “Arial” and sometimes such substitutions change the way a page is composed, usually for the worse.

Thus, to be safe, stick to the basic “system fonts” when designing a document that you expect to be distributed and read online.

ONLINE COURSE: Professional Technical Writing

+++++++++++++++++++++++++++

Lesson 17

How to Use the Bulleted Lists Properly

Bulleted lists are important in technical writing. They summarize information in a manner that is easy to read and absorb. Use them whenever you can to get your information across quickly.

Compare:

“In winter months make sure to check your tires, have enough wood for the fireplace, make sure there is are extra blankets for the guests, and the pump water is shut off.”

With bullets:

“Make sure to do the following to get ready for the winter:

* Check your tires.
* Have enough wood for the fireplace.
* Keep extra blankets for the guests.
* Shut off the pump water.”

Another comparison: which list would you remember with less difficulty:

This one:

“A knowledge of mathematics, besides geometry, trigonometry and physics, is necessary for an civil engineer to know well.”

Or this?

“A civil engineer should know his

* mathematics
* geometry
* trigonometry
* physics

well.”

But when you are drawing up a bulleted list try to use “parallel construction”; that is, the bullet items should be similar grammatically. They should have the same mood and tense. If one starts with a verb, the others should also start with a verb.

Malformed bulleted list:

“In my spare time, I love to

* go to a restaurant
* run 5K
* books are what I prefer over movies”

The first two items start with a verb, but the third doesn’t.

Corrected list:

“In my spare time, I love to

* go to a restaurant
* run 5K
* read books rather than watch movies”

As you can see, now all items start with a direct action verb. It’s now easier to remember this list.

+++++++++++++++++++++++++++

Lesson 18

When Should You Definitely Use Jargon?

You’ve heard it a thousand times and it’s true: you should stay away from jargon and write as you speak. But is this rule true ALL the time, unconditionally? No, it’s not.

There are actually times when you’d better use jargon if you want to be understood. Otherwise you’ll be stamped as an “amateur” and not taken seriously.

Take the term “deconflicting”, for example.

If the context is scheduling your day and increasing your personal productivity, “deconflicting” is a piece of painful jargon that you should avoid.

Instead of saying “You have to deconflict your priorities to finish your homework on time” it’d be a hundred times more preferable to say: “Assign different priorities to your conflicting action items
to finish your homework on time.”

But imagine you are writing a manual for air traffic controllers… a totally different context.

For air traffic controllers “deconflicting” is a very real and important concept and ALL controllers refer to that process as “deconflicting” and nothing else.

That’s their common language and lingo.

If instead of “deconflicting” you say “making sure the airplanes have distinct flight paths so that they don’t crash into each other” in order not use “jargon,” they’ll only laugh at you!

In such a special context jargon will help you establish your credentials right away as an “insider” and will help you communicate your ideas much more rapidly, with authority. That would help not only you as a professional technical writer but your audience as well since they can concentrate on the content of your copy rather than get distracted by the everyday language you’re using.

Sample Tech Document Cover

ONLINE COURSE: Professional Technical Writing

++++++++++++++++++++

Lesson 19

How to Design a Front Cover for a Technical Document

If you are a technical writer working for a company as a payroll employee the chances are there are corporate design guidelines that you need to follow in designing the cover of your technical document.

But what if you are a “lone writer,” Technical Writing – A Simple Front Coveran independent contractor working out of your home office, or an employee who is asked to come up with a corporate design guideline?

Here are some time-tested design suggestions culled from my 20 years of experience as a professional writer and information designer:

1) Keep it simple. Limit your design elements to the following components:

a) Title
b) Product/Service photo or image
c) Company logo
d) Footer

2) Title should include (if applicable) version or release number, as well as the document number.

3) Footer should include date of release, copyright and confidentiality (if any) information.

4) Leave as much white space as possible for the eyes to rest. Don’t crowd your cover page with multi-colored pictures, or fonts in different color. Try to limit your color choices to your approved corporate or client colors.

5) Leave out your name unless specifically requested by the management or the client. Anonymity comes with the territory. Your reward in technical writing is helping others accomplish complicated tasks and perform technical procedures, plus, a usually above-average monetary compensation.

6-a) If you need to include a lot of text and graphics on the cover page, do not center it like most amateur designers do. The natural sweep direction for the eye is from upper-left down towards bottom-right. Try to align your text and images along that diagonal for easy reading.

6-b) However, if you have only a few visual elements and not too much text, you can safely use a simple centered design (as shown in the illustration) to a pleasing effect.

(Illustration of a Simple Front Cover by Ugur Akinci)

+++++++++++++++++++++++++++

Lesson 20

10 Free and Open Source Applications for your Technical Documents

As a beginning technical writer you may not have the funds to buy the kind of text and layout editing programs that professional technical writers use around the world. But don’t despair. There are good and free open-source alternatives that is worth a look at. I’m personally using some of them myself (OpenOffice, Neo Office, GIMP, Inkscape) for years now without any problems.

You may want to give the following open-source programs a try.

1. OpenOffice, the king and queen of office suits. Available for PC, Mac and Linux platforms. (Try NeoOffice if you own a Mac.) Totally free and comes with a spreadsheet and slide presentation programs well. Has even a built-in PDF creator! You might be surprised with all the goodies that you can download free from The Open Office web site. I’ve been using Open Office for over two years now (alongside MS Office). I couldn’t recommend it any higher.

2. AbiWord. A lightweight word processor for those who do not need MS Word’s complexity to write simple memos and letters. It runs even on archaic hardware that does not support Open Office or MS Office. Has many features that you would not expect in a free word program.

3. Scribus is an open-source program that brings award-winning professional page layout to Linux/Unix, MacOS X, OS/2 and Windows desktops with a combination of “press-ready” output and new approaches to page layout. If you cannot afford Adobe InDesign or QuarkXpress, give Scribus a try.

4. Firefox in my judgment is the best web browser out there. I use it on all my machines. I love its tabbed browsing pages and it never crashes down. Experts agree that it is more secure than MS Internet Explorer. And it is free as well.

5. Nvu is a complete web authoring and HTML editor for Linux desktop users as well as Microsoft Windows and Macintosh users, similar to rival programs like FrontPage and Dreamweaver. I personally do not use Nvu that much because I love Adobe GoLive’s drag-and-drop CCS “floating boxes” that maxes web page design a breeze. But, if you do not want to pay a cent for your HTML editor, then I’d heartily recommend Nvu. It works fairly well once you get past its interface. It even has a great built-in FTP engine.

6. GIMP is the reason why Photoshop should be afraid. Once they get the layers functionality as polished and convenient as that of Photoshop, I think it would be hard to stop GIMP. This free and sophisticated raster image editing program will truly surprise you with its many PS-like features. I use it regularly.

7. Inkscape can become a serious competitor for Adobe Illustrator once (again) they improve the layers functionality to the Adobe level. It is a great vector drawing and editing program that use fairly regularly although I find Illustrator easier to use just out of sheer habit. But Inkspace is free as well and its Bezier curves is just as good as that of the Illustrator.

8. Wink is a Tutorial and Presentation creation software, primarily aimed at creating tutorials on how to use software (like a tutor for MS-Word/Excel etc). Using Wink you can capture screenshots, add explanations boxes, buttons, titles etc and generate a highly effective tutorial for your users.

9. PDF Creator easily creates PDFs from any Windows program. Use it like a printer in Word, StarCalc or any other Windows application. (Also: OpenOffice and NeoOffice have built-in one-button PDF creation engines.)

10. Pidgin is an instant messaging application available for free downloading. It works on Windows, Mac and Linux platforms. It is compatible with many IM networks including AIM, ICQ, Yahoo!, MSN, Jabber, IRC, Napster, Gadu-Gadu, Zephyr, and SILC.

30 Comments

  1. suma on April 28, 2010 at 11:01 am

    Excellent article describing what is technical writing.

    • Aravind on November 8, 2012 at 1:30 am

      It is an awesome article on Technical writing.
      Everything has been explained beautifully.
      As a technical writer by profession, i found it very interesting.
      Also it gives the user a brief about all the basics of exemplary technical writing
      Way to go

  2. proposalcafe (ProposalCafe.com) on August 28, 2010 at 1:19 am

    Good article titled “Introduction to Technical Writing”.
    http://bit.ly/Wj9

  3. Jon on November 17, 2010 at 12:58 pm

    Thank you for an excellent post on technical writing. It was very helpful in bettering my understanding and enhancing my skill set on the matter.

  4. Julius Meach on January 18, 2011 at 4:49 pm

    I am really thankful to this topic because it really gives great information `~,

    • admin on January 19, 2011 at 2:37 pm

      Julius, glad you liked it. Thanks for reading TCC. Let me know if you have any questions. Ugur

  5. tiranda on January 26, 2011 at 12:58 am

    This is a most helpful and comprehensive site. I’m glad I found it.

    • admin on January 26, 2011 at 2:00 am

      Tiranda, I’m glad you liked it. Stop by often as content is added daily. Best regards, Ugur

  6. nirmal kumar on March 7, 2011 at 6:17 am

    Of great help …i am on tech writing and found it more useful

  7. Q3 technologies on April 5, 2011 at 3:04 am

    Good way of presenting your thoughts. i have just gone through few of your articles on technical writing. And, i m very happy to find this content as it is very easy to understand and no doubt is very qualitative. Looking forward to read some more posts of your. Thanks for the information.

    Software documentation template

  8. Anand A on April 11, 2011 at 11:50 am

    wow really happy to read all your articles about technical writing. Thank you very much. I found them very easy to understand and i am looking forward for more post similar to this. Thank you once again for this wonderful website.

    • admin on April 13, 2011 at 8:51 am

      Anand, thanks for reading TCC. Glad to be of help. Ugur

  9. Gitanjali on June 28, 2011 at 3:43 am

    grt article..helped me sort out some basic confusions…

    • dilshad on November 16, 2011 at 4:53 am

      brilliant

      • admin on November 17, 2011 at 5:32 pm

        Dilshad, thanks for your generous praise! I hope TCC deserves it.



  10. Kausalya Janardanan on October 7, 2011 at 5:42 am

    Good tutorial on Technical Writing. Thanks. It is of great help.

    • admin on October 7, 2011 at 8:00 am

      Kausalya, thanks for reading TCC. Appreciate your kind words. Take care! Ugur

  11. Thilak on October 19, 2011 at 6:06 am

    great job!!! thanks for sharing it..really useful

  12. John Amol on January 4, 2012 at 2:58 pm

    One of the best refernce guides I’ve read in regards to technical writing. Loved it!!!

    • admin on January 4, 2012 at 3:00 pm

      John, glad to hear you liked it. Thanks for visiting TCC. Best regards! Ugur

  13. Shelly on February 7, 2012 at 8:37 am

    Wow. I went through several articles on understanding what Technical Writing is all about, but no article was of any help. I am an employee in a Marine Industry (dealing, creating and editing hundreds of documents everyday. Procedural guides, Posters, Scopes, Notices, Job Descriptions,etc etc.). Cause of which very keen to become a Technical Communicator, and YOUR ARTICLE has inspired me to become one. Thanks a Septillion.

    • admin on February 7, 2012 at 1:05 pm

      Shelly, glad to hear the introductory tutorial inspired you to become a technical communicator. It’s really a great job and career. Wish you my best! Ugur

  14. zoya on February 20, 2012 at 5:12 am

    excellent work…almost describe all relative topics…thanx

    • admin on February 20, 2012 at 8:59 am

      Zoya, thanks for visiting TCC. Best regards, Ugur

  15. Taj on February 20, 2012 at 7:14 am

    Its a really good article. Iam writing since 2006, but got into proper technical writing profession from 2 years.. Iam not much confident about my writing, people say I write well. I have not done any special study on Technical writing, so I lack that confidence that I know technical writing well…This article help me boost my confidence, it gave an overview of technical writing to me, which has helped me alot..I have also subscribed myself for Technical Writing Tips from Mr. Ugur… Thanks alot for the article, hatsoff to you.

    • admin on February 20, 2012 at 9:00 am

      Taj, thanks for your kind words. Wish you a great day and a great career in technical writing. All the best, Ugur

  16. Praven on July 11, 2012 at 6:02 am

    Thanks. Great Article. I am into Technical Writing for past 1 year and this article will help me to correct my mistakes and become a great Technical Writer.

  17. Patrick W Marsh on August 27, 2012 at 10:35 am

    Good article, it really answered the majority of my questions concerning technical writing. I’ve been a creative writer my entire life, so this should be an interesting challenge.

    • admin on August 27, 2012 at 11:03 am

      Patrick, glad to hear you liked our introductory tutorial. Creative writing obviously has its own pleasures and rewards. However, in terms of a steady paycheck, I still think nothing comes close to technical writing. Perhaps that’s why important creative writers like Amy Tan and Kurt Vonnegut have worked as technical writers early in their careers to support their creative side. If you’d like to learn more, you may want to have a look at our introductory online course: https://technicalcommunicationcenter.com2011/07/17/technical-writing-101-online-course-now-available/

  18. Dr srinivasa Gowda on November 4, 2012 at 1:01 pm

    excellent and useful

Leave a Comment

You must be logged in to post a comment.

This site uses Akismet to reduce spam. Learn how your comment data is processed.