Technical Documents

Write for your readers.

Most importantly, know your subject and your audience. The purpose of technical writing is to help your readers understand technical information—in some cases, highly technical. For your writing to be useful, your readers must be able to comprehend it. These guidelines will help you write effective technical documents.

Use good technical style.

• First of all, be accurate and precise.
  • Accurate writing is not vague. Vagueness comes from using words too broadly and not providing context.
  • Quantify what you mean whenever possible.
    • If you say something is small, define what small means.
    • If code will take a long time to compile, tell the reader approximately how long.
  • Complete comparisons.
    • If you say that X is larger, better, lower, higher, you must tell the reader what you are comparing X with.
  • Choose the words that mean literally and precisely what you are trying to convey.
    • For example, use greater than and less than instead of over and under.
• Make sure your writing is clear.
  • Clear writing is not ambiguous: it can’t be misread.
    • Avoid words with more than one meaning.
    • Use words in their primary, literal meaning.
      • For example, don’t use since when you mean because or while when you mean although, because since and while also connote time.
    • Avoid using this, that, and those by themselves; make sure that the reader knows what noun these words refer to.
    • Don’t use a slash to mean and or or, as in hot/cold extremes cause malfunction.
    • Also avoid and/or; decide which you mean and use either and or or.
    • If both conditions are possible, use x, y, and other variables to clarify your meaning.
    • Avoid due to, which could mean owed to or scheduled to; use because or caused by.
    • Do not use where to mean when or in which.
• Make sure your writing is coherent.
  • Organize your thoughts logically at the sentence, paragraph, and whole-document level.
  • Cover one topic in each paragraph.
  • Make sure your sentences and paragraphs each follow logically from the previous one.
  • Each section of the document should build on previous ones, so that they add bit by bit to the reader’s understanding. See Organize Your Writing. In section below!
  • Write short, straightforward sentences.
• Short sentences help you to explain complex ideas simply. Sentences of 10 to 20 words are easiest to write and understand.
  • If a sentence is longer, or contains several dependent clauses, break it into two or more shorter sentences.
• Use the active voice whenever possible. Use first person, active voice in most cases. The active voice is less wordy and more direct than the passive voice.
  • For example, instead of writing The algorithm was designed to answer this question, use We designed the algorithm to answer this question.
• Passive language also turns verbs into other parts of speech and “hides” the most important verb in a sentence.
  • For example, She was unable to hear the ringing of the bell is passive voice. She couldn’t hear the bell ring is active voice.

Avoid using such ‘buried’ verbs.

• For instructions, use directive language; for example, Turn the spigot to the left.

• • Ensure that your word use, grammar and style, punctuation, and spelling are correct.
    • Improper punctuation can completely change the meaning of a sentence. Most punctuation rules are part of English grammar and must be followed, but some are a matter of style. Some rules are different in British and American English, for example the rules for using punctuation with quotation marks. Rules for using commas and hyphens also vary, depending on the style guide you use.
  • Do not punctuate URLs, even at the end of a sentence. Readers may assume that the punctuation is part of the URL.
  • If your writing is sloppy, readers will wonder whether your understanding is also faulty.

Focus on your audience’s needs.

Know who your readers are and tell them only what they need to know. How much information you give, and how you express it, depends on who will use your writing.

For example, to teach non-technical people how to use software or assemble a tool, you must write more simply and give more background than you would when reporting research findings to peers in your field.

• Whoever your readers are, don’t waste their time.
  • Tell the reader how to do or get what they want as simply and directly as you can.
    • What are they trying to do?
    • What do they need to know?
      • They don’t need to know everything about the product or everything you know about your subject.
• Be as concise as possible.
  • Cut out any words and details you don’t truly need.
  • If your readers don’t need a piece of information, leave it out, no matter how interesting it is.
  • Remove empty phrases such as It has long been known that, It is worth mentioning at this point, It might be said that, and so on.
  • Use single words instead of phrases:
    • not a number of, but several
    • not the vast majority of but most or nearly all
    • not at the present time but now
    • not based on the fact that but because.
  • Omit excess words such as green in color, preliminary in nature, there are three main steps that are required.
    • Use language that is appropriate for your audience.
      • Use words appropriately for their context.
      • Do not use words with field-specific meanings to mean anything else when writing in that field.
        • For example, when you report research that uses statistical analysis, reserve significant for expressions of statistical significance.
      • Define terms that your readers may not understand or that have several possible meanings.
• If you plan to submit your writing for publication, knowing your audience includes knowing and following the publisher’s style requirements.

Style guides specifically for technical and scientific writing include:

• • MIT’s Mayfield Handbook
  • American Medical Association’s style guide
  • National Institute of Standards and Technology’s style guide
  • Microsoft’s style guide
  • Institute of Electrical and Electronics Engineers (IEEE) Computer Society’s style guide

Many are available online. Most journals, book publishers, and companies also have their own style or prefer one style guide over the others.

• Avoid unnecessary jargon.
  • Jargon can be difficult to define. Whether a technical term is considered jargon depends on your audience.
    • Even when writing for specialists, don’t overuse jargon.
    • If a simpler word will do, use it.
    • If you are not sure about your readers’ background knowledge, explain technical terms the first time you use them.
  • Some clues that you may be using jargon:
    • Too many abbreviations and acronyms
    • Words that you can’t find in a dictionary
    • Abstract words and phrases such as amenities, elements, structures, systems, and so on.

Organize your writing.

• Organize the text logically so that readers can find the information they need.
  • Order information so that readers can use what they already know, and what you already have told them, to understand new information.
  • Lay the text out so that its overall organization is easy to see.
  • Ensure that the layout also points readers to key information.
• Format your document consistently.
  • Use heads and subheads the same way each time.
  • Ensure that the type size and font are the same in each section for each level of head.
  • Start each with the same part of speech (noun, verb, gerund).
• Start with an introduction, outline, or table of contents, so readers know what they will find in your document.
  • An introduction can be as brief as a paragraph or several pages long. For reports, it should tell readers why you wrote the document and what they can expect to find in it.
  • If you are designing a website, the Home page is your introduction. Resist the temptation to create a cool, animated splash page just because you can. A beautiful display that doesn’t give your visitors useful information simply wastes their time.
• Develop your outline first. The outline is like the skeleton of your document. A good outline defines the overall shape of a written work and displays its internal logic.
  • Write down your title: what is your subject?
  • Under the title, list all of the major topics you will cover, in the order in which you’ll cover them.
  • Under each major topic, list all of the minor topics required to cover the major one adequately.
  • If you craft your outline carefully, you can use these topics and subtopics as the heads and subheads in your document or website and as the basis for your table of contents or site map.
• List every part of your document and give the page number on which each part starts.
• Make information easy to find by using heads and subheads.
  • Use heads (short for headlines) or links to organize the material in each major topic.
  • Tell readers what they will find in that section.
  • Make heads as descriptive as possible: not Process Overview but How the Assembly Line Works.
  • When possible, name the reader’s goal in each head or subhead: Getting Started in XML, How to Change Drill Bits.
  • Use strong verbs and specific nouns.
  • Use subheads to organize the subtopics under each major topic. Follow the same rule as for heads.
• Break text into brief one-topic paragraphs.
  • Limit paragraphs to no more than 10 or 12 lines of text.
  • If your paragraphs are too long, try breaking them up by topic, subtopic, or individual idea or making them into lists.
  • For a website, consider linking to another page or a pop-up window.
• Use bulleted lists, numbered lists, and graphics to outline and illustrate key information.
  • A list can be a good way to break up a long sentence or paragraph. Lists are also a good way to preview the material you cover.
    • Use bullets when the order of the items in a list doesn’t matter.
    • Start each item with the same part of speech (noun, verb, gerund).
    • Keep items in lists brief, ideally no more than one line of text.
  • Use numbers list only when the order of the items in a list is important.
    • Good uses of numbered lists are instructions that must be followed in a particular order, items listed by size, or events that occurred in a specific order.
    • Start each item with the same part of speech (noun, verb, gerund).
    • Keep items in lists brief, ideally no more than one line of text.
• What kind of graphics you use depends on the kind of document you are writing.
  • Software manuals commonly use images that show the parts of the computer screen affected by the action being described.
  • Flowcharts are good for describing complicated processes.
  • Diagrams are an efficient way to show how a thing is put together.
    • Number every graphic you use and describe in the text what each one illustrates.
• Don’t imbed equations in text; put them on separate lines so they’re easy to see.
  • Identify each of the variables and parameters in an equation when you first use them in the text.
  • Number equations in the right-hand margin so you can identify them in the text.
• For long documents and complex websites, provide an index or site map.
  • In a print document, an index is an alphabetical list of all major and minor topics and the page numbers on which they can be found. The index is always put at the end of the document.
  • A website index (also called a site map) is a single page that links directly to the topics. Whether your index is printed or electronic, its purpose is to give your readers easy access to the information they want.
  • Create a graph or outline that illustrates how the pages link together. Site maps improve navigation and help readers find the page they want.

Organization is especially important when you write content that will be read online.

• Design the overall structure of the site before you start to write.
  • Start with an outline.
  • Determine the site navigation: how will topics be linked?
  • Write all of your heads and subheads on sticky notes.
  • Arrange them on a wall into a rough site map.
  • Ask colleagues to test it by telling you how they would expect to get from one part of the site to another.
  • Reorganize the site based on their feedback.
• As with print, use heads and subheads to help readers figure out how the information is organized.
• Put one major topic on each page and link to related topics.
• Make links obvious, so that visitors will be confident that they will find what they need.
• Aim to fit each page of text onto no more than a screen and a half. Visitors’ page views will vary, depending on their screen sizes and browser settings.
  • Avoid making your visitors scroll down long pages of solid text.
  • Instead, break your text up into short paragraphs, grouped by topic.
    • Limit paragraphs to no more than 10 or 12 lines of text.
    • If your paragraphs are too long, try breaking them up by topic, subtopic, or individual idea or making them into lists.
    • For a website, consider linking to another page or a pop-up window.

Test your writing.

Technical writing that readers don’t understand, or can’t use, has failed. Despite your best efforts, readers are likely to misunderstand what you write, have trouble following your instructions, or get lost at your website. Therefore, to be sure that what you write is useful, you must test it.

• Ask several people to read your writing and summarize the findings of your report, follow the instructions in your user guide, or navigate through your website. Observe them, but don’t help them. If they become confused, find out what is confusing them. Then rewrite that section.