General Guidelines for Technical Writing of User Manuals

I have usually worked on creating User Manuals for my company and so I will write up some posts for writing technically while creating User Manuals.

• Provide a real (physical) User Manual with the product: don't make people read a pdf.
• Make sure the instructions actually map on to the product in all respects.
• Include a one-page quick start guide.
• Present instructions as step-by-step procedures.
• Tell the user what functions there are, and what they are for — not just how to use them...
• ...but avoid marketing waffle (they already bought the product!)
• Ensure that the writers are part of the product design team.
• Write the user manual in sync with the product's development timeline — not under pressure of shipping deadlines.
• Make sure the writers have the product, understand the product, and actually use the product as they write.
• Consider the needs of disabled users (i.e., low vision, colour-blind) and provide alternative manuals in Braille, large print, audio etc.
• User-test the product and the user manual with real users (including disabled users).

Effective Technical Writing Guidelines - 2

1. Writing Guidelines: A Closer Look

   
   

   1. Organize information logically
   • Group similar things together.
   • Order those groups appropriately.
     The "appropriate" order depends on the situation. For example:
   • If you are describing a process, list the steps chronologically
   • To explain something, move from general to specific points
   • To document a project try ordering by problems-methods-solutions
   • To persuade, order your arguments from most to least significant.
   
   
   2. Provide cues to help readers follow and find information.
   • Use headings, lists, and other formatting devices to make the information accessible.
   • Use forecast statements to preview what is ahead. Use summary statements to review what you've covered.
     In this example, the writer has previewed the specific points that her proposal will cover and the order in which she will discuss them:

   "This circuit can be broken into four blocks:

   o The square and triangle generating portion

   o The JFET-based circuit

   o The module that uses the square and triangle waves to form a saw tooth

   o An amplifier with adjustable gain"

   3. Make the proportion of space you give to any information reflect the relative importance of that information.

   4. Choose words precisely

   o Use technical terms correctly and appropriately for the audience. Avoid unnecessary jargon.
   "We will use different capacitors in order to cancel out the glitch."

   
   

   o Avoid vague words.
   "The circuit experienced some difficulties."
   Which circuit? What is a difficulty?

   
   

   o Avoid ambiguous words and phrases (especially "this" and "it")
   "When the square wave is negative, the inputs to the op-amp are grounded, and the input signal is inverted. This produces a double-frequency saw tooth of the same amplitude as the input."
   What's "this"—a negative square wave? grounded inputs? an inverted input signal? all of these?

   
   

   o Use strong verbs.
   This example obscures the "real" verbs:
   "The component count of the circuit is kept minimal with the use of an integrated circuit (IC) JFET operational amplifier in the input stage."

   
   This revised version features stronger verbs:
   "The design uses an integrated circuit (IC) JFET operational amplifier in the input stage to minimize the number of components." [emphasis added]

   
   The following example suffers from a weak verb and from wordiness:
   "Proposal: The proposed Frequency-to-Voltage converter is part of a three person collaboration to build a circuit in lab that, ideally, could be employed, for example, in the transmission of touch tone phone conversations."

   
   The writer also uses a cumbersome noun phrase ("employed . . . in the transmission of") to express the real action (simply to "transmit"). Also, notice the unnecessary phrases ("ideally, could be employed," "for example"). As revised:
   "Three students propose a collaborative project to build a Frequency-to-Voltage converter that could transmit touch tone conversations."

   5. Write Clear, Concise sentences

   o Avoid wordy phrases.
   Some wordy phrases can seem to sound "smarter" than simpler ones. But wordy writing can make documents excessively long and frustrate a reader. You can often replace a bulky phrase with something more concise. Paring down such phrases can substantially shorten a long document without compromising your meaning.

   
   

   Wordy	Concise
   a majority of	Most
   a number of	few, many
   subsequent to	After
   in order to	To
   in view of the fact that	because, since
   based on/due to the fact that	Because
   during the course of	While
   for the purpose of	For
   with regard to	about, concerning
   in the event that	If
   so as to	To
   take into consideration	consider
   have the capability to	Can

   
   

   o Combine short, choppy sentences.
   "We found a solution. The solution can be displayed on an oscilloscope."
   Revised:
   "We found a solution that can be displayed on the oscilloscope."

   
   

   o Generally, favor the active over the passive voice.
   In the active voice, the subject of the sentence ["design"] performs the action ["offers"]:
   "This design offers more advantages."
   
   

   In the passive voice, the subject receives the action. Passive sentences are usually longer, more complicated, less direct than active ones. Writers sometimes favor passive voice because it can seem to sound more scientific or objective than the active voice:

   
   "In this design, more advantages are offered."

   
   As this example shows, active sentences are usually shorter and more direct than passives. Use the active voice unless you have a good reason not to.

   6. Review drafts for problems in format, spelling, punctuation, units of measurement and labels for figures. Proofread! Allow some time (if only just a few hours) to pass between drafting and revising the document.

   
   

   o Edit in Stages

   o Make a first pass to see if the organization is good and the information is correct. (You might even make an outline from your first draft after you've written it, to check whether the sequence is logical.)

   o Make another pass to check phrasing and spelling.

   o Reading aloud can help you spot any wording that needs revision.

   o Use your word processor's spell checker, but remember that it will not catch all errors. You must also proofread.

   o Learn from past mistakes . . . and past successes. As you write each new assignment, remember the comments your past writing has received. Keep these in mind as you revise.

Effective Technical Writing Guidelines - 1

In my last post I had explained in brief, the important points to be taken care of while writing technically. This post will explain the methods for effective technical writing.

Let us first understand the mistakes that we as Technical Writers and Software Programmers are prone to making. Usually professors of technical writing and senior staff in the organization are concerned with some very common mistakes that we practitioners of technical writing keep repeating.

• Unclear purpose or context
  "At the start, I don't know why I'm reading the report. I don't understand how the specific information I'm getting fits into a larger situation. Does the writer know why I requested this information?"
• Baffling organization or logic
  "I don't understand where the writer is going or why I am getting one piece of information before another. I can't figure out how idea A leads to B and how A and B relate to C or D."
• Lack of clear conclusions
  "When I finish reading, I want to understand why the information is important to me. I want a good answer to my question, 'So What?'"
• Too much or not enough detail
  "The writer spends too much time discussing unimportant aspects and not enough time on what is most significant to me. The emphasis is misplaced, maybe to hide what the writer doesn't know."
• Muddled sentences, garbled expression
  "Individual sentences are difficult to untangle—wordy and ungrammatical. I resent spending time on this report."
• Sloppy or imprecise use of technical terms and concepts
  "The writer does not understand the engineering terminology, or misapplies it, or inappropriately addresses it to a reader who is not at this technical level."
• Faulty mechanics
  "What a mess! The document has errors in format, spelling, punctuation, and units of measurement. Diagrams are labeled poorly or not at all."

Writers' Obligations

Our challenge, as writers, is to anticipate such objections. If we want readers to understand and appreciate what we write, we need to make their job as easy as possible. We can translate readers' complaints into three overall considerations and six specific writing guidelines:

Three Overall Considerations

• Consider your audience.
  Understand you readers' needs, attitudes, familiarity with the subject matter, and technical level. Adapt your writing to these things. Decide in advance what your audience should think when they finish reading your document.
• Consider the situation.
  Know the context in which your writing will be read and judged. Shape your writing to it.
• Develop a sound writing process.
  Good writing results from a process that includes gathering information, brainstorming and organizing ideas ("pre-writing") as well as drafting, editing, and revising. Don't expect your writing to flow out wonderfully in a single try. Although you are very busy, try to spend some time composing in stages: prewriting, drafting, and revising each assignment.

Six Guidelines For Effective Writing

1. Organize information logically.
2. Provide cues to help readers follow and find information.
3. Make the proportion of space you give to any information reflect the relative importance of that information.
4. Choose words precisely.
5. Write clear, concise sentences.
6. Review drafts for problems in format, spelling, punctuation, units of measurement, labels for figures. Proofread! Allow some time (if only just a few hours) to pass between drafting and revising the document.

How to Write Technically?

Writing is an art, no doubt. But anyone who can speak and write flawless English can become a good technical writer. Writing Technically isn't a very tough task. All it requires is understanding the content and reproducing it in carefully worded sentences.

Inspite of this, more often than not, most people involved in the software industry make a lot of mistakes while creating their functional and design documents. One of the reasons I believe why this happens is that software professionals do learn a lot of languages while at school earning their degrees, but they do miss out on learning how to write technically.

There are some basic points that one should adhere to while writing technically. I will be enumerating them below:

Use Active Voice and Present Tense.

Write Clear and Concise sentences.

Avoid technical jargon. While writing, try to keep the audience in mind at all times and you will avoid a lot of mistakes.

Write short sentences. Try and write 10 to 20 words in every sentence.

Try to document One Task in One Sentence.

Do not use acronyms that are not explained in the document.

Avoid ambigious sentences and large words.

Keep Short Paragraphs.

Use Bullets and Lists wherever possible.

Use Charts, Diagrams and Figures wherever possible.

Write Precisely, Accurately and very Carefully while defining terms.

Use Headings and Subheadings generously.

Repeat the same set of Formatting Guidelines and Words as often as possible in the document. This will ensure that the reader will soon become comfortable in reading your document and understand it better and faster.

Finally, Edit, Edit and Edit your document before you submit it.

We will learn and discuss all these topics in detail in the next few posts that I write.

Technical Writing Primer

What is Technical Writing?

Technical Writing, is a form of writing that is used in many diverse fields to explain technology and related ideas to technical as well as non technical audiences. Technical Writers are involved in the creation of various different types of documents that are used in many different fields from computer software and hardware to consumer electronics and biotechnology.

Every profession has a specific way of writing that it follows. Most white collared professionals generate documents relevant to their specific fields. The lawyers, policemen, social workers to the software programmers and instructional designers all follow their own unique modes of writing. Technical writers are generally involved with creating documents for and about technology.

Typically, Technical Writers gather information from the Subject Matter Experts – SMEs and existing documentation on the subject. This information is then reproduced depending on the audience and its requirements by the Technical Writer. This is one reason why it is important for anyone in the field of Technical Writing to possess strong language and teaching skills.

Technical Writing aims to provide information to people in a clear, concise and directmanner. In general, Technical Writing is considered to be dull as compared to other forms of writing because of all the constraints it has to put up with. But, inspite of this, a good Technical Writer is expected to come up with ways to engage the audience. Technical Writing should not leave any room for imagination besides anticipating and answering any questions or problems that arise.

What do Technical Writers do?

Beyond the technicalities of the work of a Technical Writer, I will try and provide you a brief overview of what is a typical Technical Writing job.

1. Audience Analysis
All forms of write ups depend on the audience at which they are aimed. A technical writer starts with Audience Analysis and tries to understand who he is writing for.

2. Information Assimilation
A technical writer assimilates information from Subject Matter Experts-SMEs, existing documentation and even from the code he or she is expected to write about.

3. Delivery
Finally, the technical writer will prepare the product for delivery based on the type of documentation eg. Product Manual, User Guide, Online Help etc., that he is expected to produce.

What are the characteristics required to be a good Technical Writer?

Now, that we know what a Technical Writer does, the answer to this is simpler.

1. Curiosity

A curious writer will try and understand a subject better than any other. Curiosity is what Technical Writers thrive on.

2. Learning Ability
If you are curious, you will know and if you know, you are bound to learn.

3. Teaching Ability
Being able to express one self in the most simplistic terms is the hallmark of a good teacher. And this is what produces great Technical Writing too. A good technical write up is one which is understood by being read only once.

4. Eye for Detail
A Technical Writer must understand punctuation, style and syntax and use this to highlight and present the documentation prepared.

Some Links for More information on Technical Writing:

http://www.essortment.com/all/whatistechnica_rdcm.htm

http://www.wisegeek.com/what-is-technical-writing.htm

http://jerz.setonhill.edu/resources/FAQ/TW.htm

http://en.wikipedia.org/wiki/Technical_writing