Technical Documentation Terms

Here are some Technical Writing Terms Every Technical Writer Should Know…

Documentation Guide

A comprehensive project document that is prepared before the documentation process starts.

The Documentation Guide specifies the title, content and purpose of the document; the stake holders and authorized parties; the delivery format and schedule; chapter outline; software or hardware needed to finish the projects; risk analysis (things that can go wrong and their impact of the project; methods to compensate the impact); deadlines; etc.

The technical writer should not start writing anything before the Documentation Plan is signed and approved by an authorized Manager or Client Representative. That way, in case of a disagreement, a writer can always go back and refer to the approved Documentation Plan. It is highly recommended.

Functional Writing

Functional Writing creates the kind of entry-level document that explain which “button” or part 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 and parts/components of a gadget, without telling you the BEST WAY to use the product.

See “Procedural Writing”

Guide

See “Manual.” Very similar, except it has less of a “hand” and more of a “discovery” connotation. A set of instruction to guide one in fixing a problem, installing and configuring an engine, a system, etc.

Typical: USER, INSTALLATION, CONFIGURATION, SYSTEM ADMINISTRATION guides.

(c.1374, from O.Fr. guider “to guide, lead, conduct,” from Frank. *witan “show the way,” from P.Gmc. *wit- “to know” (cf. Ger. weisen “to show, point out,” O.E. witan “to see”). The Fr. word infl. by O.Prov. guidar (n.) “guide, leader,” from the same source. The noun meaning “one who shows the way” first recorded 1362. Guidance is first recorded 1590, replacing 15c. guying. With reference to problems and advice (in school, career, etc.) it is first recorded 1927. In 18c. France, a “for Dummies” or “Idiot’s Guide to” book would be a guid’ âne, lit. “guide-ass.”
http://www.etymonline.com/index.php?search=guide&searchmode=none)

Manual

Interchangeably also called a “guide.” A set of instruction one kept “at hand” to fix a problem, to install and configure an engine, a system, etc.

Typical: USER, INSTALLATION, CONFIGURATION, SYSTEM ADMINISTRATION manuals.

(“1406, from L. manualis “of or belonging to the hand,” from manus “hand, strength, power over, armed force, handwriting,” from PIE *men- “hand, to take in one’s hand” (cf. O.E. mund “hand, protection, guardian,” Ger. Vormund “guardian,” Gk. mane “hand”). The noun is attested from 1431 and originally meant “service book used by a priest,” from O.Fr. manuel, from L.L. manuale “case or cover of a book, handbook,” neut. of L. manualis. Meaning “a concise handbook” of any sort is from 1533.”
http://www.etymonline.com/index.php?search=manual&searchmode=none)

Procedural Writing

Procedural Writing, in contrast to “Functional Writing,” is harder 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.

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

See “Functional Writing”

Review

A crucial part of every documentation process. A technical writer should try to determine who should be on the Review Team while still writing the Documentation Plan. More often than not, review cycles take longer than expected due to the other responsibilities that most reviewers have in a corporate setting. Reviewers are usually SMEs (Subject Matter Experts) that provide valuable feedback on how to improve a document.

Peer Review is the review provided by a technical writer’s peers, who are usually other technical writers working on the same team, or for the same department or company.

SME

Subject Matter Expert. SMEs are invaluable sources of data, review and feedback for technical documents.

Structured Writing (or Authoring)

The method of writing in which the XML code underlying the document dictates the structure of the document, as well as its formatting.

For example, in structured writing one can dictate that Heading 1 style is and must be followed by a Heading 2 style text. Or one can dictate that a Figure Caption must follow every Figure. The “structure of rules” underlying a structured document will not allow technical communicators to enter and format document composes as they please.

It is a highly-disciplined form of writing that is still developing at this writing since there are no universally accepted standards and tools of structured authoring. DITA (Darwin Information Typing Architecture) and DocBook are two such standards. Some widely-used XML-based structured authoring text editors include FrameMaker, PTC Arbortext Editor, JustSystems XMetaL, Syntext Serna, oXygen, and XML Spy.

See “Unstructured Authoring”

RESOURCES:

Structured Authoring and XML (PDF file)
http://www.scriptorium.com/structure.pdf

XML Authoring Tools
http://www.infomanagementcenter.com/enewsletter/200701/fourth.htm

Content Parsers and Structured Authoring (zipped PowerPoint file)
https://www.stc.org/edu/55thConf/download.asp?ID=29

5 Minute DITA Presentation (Flash slide show)
http://www.ditausers.org/training/DITATopics/

Unstructured Writing (or Authoring)

That’s “regular writing” without any XML structuring. When you write a document with a regular text editor, you can format any header, any paragraph, any word anyway you like. You can change the position of the chapters, sections and paragraphs; change the color and font styles; you can practically write it anyway you like. It is contrasted to “structured authoring” which is a recent development in technical writing. Throughout human history, all writing has been “unstructured writing” (or authoring) by default, until the late 1990s when the first “structured authoring” editors started to be used by the technical communicators.

See “Structured Authoring”

MORE INFO

Software Documentation Terms You Should Know As a Technical Communicator

General Resources on Technical Writing

Handbook of Technical Writing, Ninth Edition
Kaplan Technical Writing: A Resource for Technical Writers at All Levels
Technical Writing for Dummies
Developing Quality Technical Information: A Handbook for Writers and Editors (2nd Edition)
Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation, Second Edition
Spring Into Technical Writing for Engineers and Scientists