Technical Writing Aid

Technical Writing Guide

Document Development Life Cycle (DDLC)
The document development life cycle (DDLC) is a guideline for developing documents. The DDLC is a standard series of steps that can be specialized for any project. There are seven steps in a standard DDLC:

  1. Project Start Up - Project identification, outline and creation of objectives, timeline, goals, standards, personnel assignment, restrictions, and cost estimate.
  2. Requirement Analysis - The team performs audience, needs and task analyses and decides on the final format and delivery.
  3. Designing - The team collects data and details all design aspects.
  4. Developing - The technical writer formats the document template and writes the first draft. The SME and substantive or technical editor make corrections. The writer rewrites until the document is ready for the next stage, testing.
  5. Testing - Test subjects trial the document for precision, correctness, and usability to verify its quality.
  6. Publishing - The copy editor, proofreader and layout artist ensure the document is free of errors and perfectly formatted before releasing it to Production and Circulation for delivery to the audience.
  7. Maintaining - The document is named or coded correctly and archived by the librarian or administrative assistant, so it can be easily retrieved and updated. Proper nomenclature, security coding, and file type make it is possible for any authorized person to revise the document, not just the original technical writer.

Document Design
Every document, whether it is a two-page brochure or a 200-page user manual, must be well designed and formatted. Creative and marketing writers are expected to design new and unusual layouts. However, technical writers must design clean, predictable, coherent material in a standardized fashion. Here are some reference standards for good document design:

  1. Cover page - Do not number the cover page. Center the title of the document on the page in large type. It is appropriate to place the company logo on the cover page.
  2. Title page - After a blank inside front cover, the title page contains the working title, code number, and version number to indicate revisions. If the title changes during development, cross-reference the title to the cover page, so it is only necessary to change the cover page.
  3. Table of contents (TOC) - Always begin the TOC on a right-hand page. The first TOC page contains a footer but no header. If the TOC runs into more than one page, then additional pages have headers and footers.
  4. Introduction - Always begin the introduction on a right-hand page. It does not need a header but should have a footer. Introduce the document and, if necessary, clarify its formatting for the audience.
  5. First page of chapter - Always begin the chapter on a right hand page. It does not have a header but does have a footer with the number 1 as an Arabic numeral.
  6. Chapter pages - The chapter pages after the first page all have headers and footers. The page numbers of left and right hand pages mirror each other.
  7. Index - Always begin the index on a right-hand page. It does not have a header but does have a footer. Number the index in Arabic numerals continued from the rest of the text. Indices contain two columns and use a smaller font than the rest of the document.
  8. Inside back cover - Leave this page completely blank.

Glossaries
Glossaries contain definitions for words in the document that might be unfamiliar to the reader. Always begin a glossary on a right-hand page with a footer but not a header. Glossaries can be very difficult to write. Some words cannot be found in a dictionary or online and require extensive research by the writer. The technical writer must understand the definition of the word and then rewrite it in language the user can comprehend, at about a Grade 8 level. Do not copy phrases exactly (plagiarism). Your SME is probably not a good source for obscure definitions because he or she is a technical specialist who is given to jargon.

A good online source that incorporates many different online dictionaries is OneLook at http://www.onelook.com. If the term is an abbreviation or acronym, then use http://www.acronymfinder.com. Use major search engines, such as Google, Yahoo, and Mama, if the term is more obscure. Some searches will lead the technical writer to Request for Comments (RFCs) or standards, which are documents used in computer engineering. These documents are very technical and difficult to read but might be the only source available for some glossary terms.

Some technical writers create a company glossary that lists acceptable terminology within the organization. A company glossary is highly useful because the terms will be consistent in future projects within the same company if their definitions remain the same.

The standard requirements for a glossary are:

  • Sort it alphabetically.
  • If a word begins with a number, alphabetize it as if the number is spelled out. For example, place 10-40EZ between "tag" and "time" because it is pronounced "ten forty ee zee."
  • Do not define abbreviations or acronyms. Redirect the reader to the entire phrase. For example:
    • SME - See subject matter expert
    • Subject Matter Expert - One who is an expert on a particular subject
  • Keep entries short. Do not write lengthy, extensive entries.
  • Define nouns as opposed to verbs (e.g., writer rather than writing)

When the glossary is complete, give it to the editor and at least one other person for review.

Copyright
A copyright marks a fixed piece of intellectual property as exclusive to its owner automatically, from the time it is created. A fixed work can be a computer file (saved or unsaved), or recorded broadcast, or printed material, or an image. An unrecorded lecture, for example, is not a fixed piece of intellectual property. An idea, title, slogan, list of ingredients, method, or concept cannot be copyrighted.

Intellectual property means published or unpublished literary, dramatic, musical, choreographed and artistic works. Examples of intellectual property include: Technical documents; architecture; movies; phonorecords (cassette tapes, CDs, vinyl disks, and MP3 audio files); novels; play scripts; sculptures; dances; pantomimes; lyrics and sheet music; and illustrations (line drawing, painting, map and photograph).

The writer might be the owner, or may have sold his or her rights to a publisher as a work-for-hire. Examples of work-for-hire include: Translations; tests and answer keys; compilations; an atlas; any collaborative work, such as an anthology or a periodical. Most technical writers perform work-for-hire. (Even if the writer sells all rights to the publisher, the writer retains moral rights under international law. This means the writer has the right of attribution and can claim authorship in a resume, for example.)

Buying a book, CD, painting, or other piece of work does not entitle you to reproduce it. If you want to photocopy or otherwise reproduce copyrighted material, you must obtain the written permission of the owner or through a Rights Management System, which grants a pay-per-use or yearly license, such as Access Copyright at http://www.accesscopyright.ca/Default.aspx?id=233. If you want to quote a reasonable passage from another writer's work in your document under "fair use" law, you must give attribution. An example of "fair use" is quoting a short passage from a book in a newspaper review. If you rely on another author's research in your document, then you must include a citation beside it, for example: (Smith, 2009). You can also give a statement, for example: "As John Smith indicated in his 2009 book, How to Count a Dog's Fleas..."

The symbol for copyright is ©, but it is also legal to print "Copyright" in full, or to abbreviate it as "Copr.". Since the Berne Convention of March, 1989, use of the copyright symbol has been optional. A copyright does not need to be officially registered to be recognized in court. However, a copyright notice gives the viewer fair warning that the work is protected and should not be reproduced without legal authorization. If a copyright notice appears at the beginning of a document and it is illegally copied, then the defendant cannot claim innocent infringement (not realizing the document is protected).

The United States protects writers whose works were created in countries that signed the Berne Convention of 1989 or The World Intellectual Property Organization Copyright Treaty of 1996. Internet and electronic work falls under the latter treaty.

New works are copyrighted for 35 years. Works made prior to 1978 have an extended copyright of 95 years. You can copyright your document online, without the aid of a lawyer or agent, through the electronic Copyright Office (eCO) at http://www.copyright.gov/ for $35. (Electronic registration is cheaper than surface mail registration.) You must subsequently deposit two hard copies of published work with the Library of Congress at 101 Independence Avenue SE in Washington, DC. You must deposit one copy of unpublished work. If you are worried that an unscrupulous person may steal your work before you finish it, you can preregister it, pursuant to the Artists' Rights and Theft Prevention Act of 2005.

If you choose to put a copyright notice at the beginning of your print document, write it this way:

© [Year of publication] [Name of copyright owner]. All rights reserved

There is no period after "All rights reserved" in a copyright notice.

If you choose to put a copyright notice at the beginning of a sound recording, write it this way:

©[Year of publication] [Name of copyright owner]

Your company lawyer determines the final placement of the copyright notice on the product and its contents. For the first draft, place the copyright notice at the beginning of your document on a separate page. Place your company's copyright notice and trademarks first. Follow your company's copyright notice with the copyrights and trademarks of any other parties or products mentioned in your document.

The trademark symbol (™) indicates that a company has officially registered a distinctive logo, symbol, sign or word with the appropriate authority. The trademark's owner places the distinctive symbol or other identifier on a product to indicate it is genuine. A trademarked symbol is restricted for use by one owner. A trademark is granted for seven to 20 years and can be renewed. An example of a famous trademarked word is Coke™, a trademark of The Coca-Cola Company.

Construct a Basic Technical Report
Change the general format for a basic technical report, below, to suit your project. A technical report should contain the following elements:

  1. Title - An identifier or name that can be numerically coded or can state the purpose of the report (e.g., XYZ Corp. 2009 Annual Report)
  2. Author - The writers' names
  3. Abstract - Summarizes what the report is about in 100 words, unless the document is
  4. Introduction - States the reason for publishing the report, e.g., to investigate and solve a problem, or as background information, argument, or hypothesis.
  5. Experimental - Explains the experiment in detail, including equipment, method and technique.
  6. Results - The data resulting from the experiment.
  7. Discussion - Evaluates the successes and failures of the experiment.
  8. Conclusion - Data analysis and the outcome of the experiment are discussed.
  9. Recommendation - An optional step, where the writer proposes a solution and requests future investigators cite the work in future documentation about the same problem.
  10. Acknowledgements - Commercial sponsors, supportive organizations, and financial backers are listed so the reader knows if there is a conflict of interest or undue influence.
  11. References - A list of research sources consulted and cited; may be in chronological order or in order of their appearance in the document.

Fonts
A font is a set of type in one face for all characters (letters, numbers, punctuation marks, and symbols). For example, 12-point Cambria is one font. The technical writer chooses the fonts for the project. The graphic artist must use the appropriate font for captions, so their work is consistent.

A font family is closely related typefaces that vary in weight (blackness or lightness), emphasis (roman, bold, underlined, or italic), and width (regular, condensed, or narrow). For example, Cambria is a font family and here are two individual fonts in the same family:

A serif is a tiny stroke or tail on a character that makes lengthy body text easier to read because it seems to flow together. Examples of serif fonts are Times New Roman, Garamond, and Bookman. Sans serif fonts lack the tails and are appropriate for headlines, signs, and captions. Examples of sans serif fonts are Arial Black, Lucida Sans Unicode, and Arial Narrow. Verdana is a sans serif font created for the Web.

Use no more than three different fonts in the entire document, to avoid confusion and clutter. Use italics for book titles and sparingly for emphasis. Three common fonts installed on every computer are Arial, Courier, and Times New Roman. Use these common fonts so your document is legible on most computer systems. If your reader does not own an exotic font, then the computer substitutes characters or they read as majibake garbage. Here is an example of majibake:

Incorrect tags and coding errors also result in majibake garbage in a browser.

Online Product Descriptions
A product description is a detailed report of a product or service. In addition to listing its qualities and uses, a well-written description is a sales tool that helps convince potential buyers to try a product. Most readers are already interested in the product and just need convincing information to sway their decisions. Technical writers give online product descriptions of computer software, hardware, and consumer electronics. Include these elements in every product review:

Product Image
A photograph or line drawing captioned with descriptive words that highlight the look, sound, or feel of the product.

Functions and Benefits
The consumer needs to see the product's usefulness. Show the consumer how the product works and how it could streamline work or make something easier to use. Include ordering information about the product's size, weight, color, and serial or item numbers.

Customer Reviews
Reviews can sway an undecided buyer. Testimonials from current customers that list the positives about the product benefit sales. Customer reviews must be authentic to add credibility to a product. The review must illustrate how "real" people use it.

Ordering Information
Online product descriptions contain the name of the company and the contact information for ordering (Web site, telephone number, and address), prominently displayed.

Editing Technical Writing
All professional writing requires editing by a professional editor. Editors do much more than check for grammar, spelling, and punctuation errors. Editors are also responsible for the following types of edits:

  • Language Edit - This is the "standard" edit familiar to most people. Editors look for proper spelling, grammar, punctuation, syntax, terminology, flowing transitions between paragraphs and chapters, and cohesion.
  • Policy Edit - Companies with strong standards and values want them followed consistently in all of their publications. Trademarked logos and other proprietary company information must be presented in a legal manner.
  • Integrity Edit - Technical writers create documents with uniform page numbering, indices, tables, and numbered graphics. An integrity edit ensures everything matches and follows the same style.
  • Format Edit - The document layout must be consistent regarding margins, font, pagination and white space.
  • Substantive Edit - The technical editor ensures all essential material is present and that nothing of importance is missing. The technical assesses the usability of the document and edits for clarity of expression.

A good technical editor is organized, responsible, pays attention to detail, works well under pressure, and accommodates a variety of people. Some technical writers move on to become technical editors; their writing experience helps their success as editors.

Technical Writing - Main


Last Updated: 07/29/2014

© Copyright 2017.

All rights reserved. TechnicalWritingAid.com

| Contact Us