Lead Writer: Steve Moss | Peer Reviewer/s: Kieran Morgan | Managing Editor: Kieran Morgan

This chapter explains essential principles of the writing aspect of technical writing. It covers strategies for empathizing with readers, organizing complex information, and crafting polished prose. Each section offers practical examples, dos and don’ts, and advice on applying these principles within the framework of your style guide and house style manual. This is a comprehensive guide for technical writers seeking to elevate the quality and efficiency of their work.

Who Should Read This
• Aspiring Technical Writers • Beginner Technical Writers • Cross-Domain Professionals
Table of Contents: Technical Writing Process
Previous: Chapter 15: Design Templates	Next: Chapter 17: Write Draft

1. Introduction

Step into the world of masterful technical writing with this chapter. Drawing on the wisdom of technical writers with decades of experience, we focus on the core principles underpinning high-quality, efficient technical writing. You’ll learn how to communicate complex information effectively to your audience. This chapter provides insights on applying these principles, enriched with practical examples as well as the dos and don’ts of the craft.

Your guides on this journey are your style guide and house style manual. These indispensable tools aid in perfecting the pesky finer points of technical communication, such as the proper placement of commas in a bulleted list.

What Does That Mean?

Style Guide A manual of guidelines on grammar, punctuation, layout, formatting, structure, and other stylistic aspects of writing. An example is the Chicago Manual of Style in the United States. Style guides vary from country to country and across different industries. House Style Manual An organization-specific (or even team-specific) style guide. House style manuals contain guidelines on how to write in the organization’s style, dos and don’ts, trademarks, legal boilerplate, the correct tone to adopt, and other relevant details.

2. [Theory] Empathizing with Your Audience

In this section, we explain audience-centric technical writing. The key to crafting excellent technical documentation lies in empathizing with your audience. This segment builds upon the foundation laid in our discussion on audience analysis in Chapter 11: Analyze Audience.

Insight

The Technical Writer as an Audience Advocate In technical writing, think of yourself as the audience’s advocate. Your job isn’t just to relay information; it’s to ensure the information is understandable and relevant from the reader’s point of view. This means constantly asking, “Will this make sense to end users?” By adopting this mindset, you bridge the gap between expert knowledge and the reader’s needs to make complex information accessible and useful.

2.1. Key Principle: Relevance

Imagine you’re a curator tasked with assembling only the most compelling pieces for an exhibition. That’s your role when applying the relevance principle in technical writing. Your goal is to sift through information and select only what is most relevant for your audience. This principle isn’t just about what to include but also what to leave out. Because you’ve gathered a wealth of information from subject matter experts and existing technical documents, it’s tempting to showcase it all. Resist the temptation! Great writers use only what’s absolutely necessary.

Consider the following when applying the relevance principle:

1. Relevance to the section: Does the information enhance the specific topic you’re addressing at this moment?
2. Overall document relevance: Does it fit the document’s purpose, offering value to your audience regarding the product or service in question?

When to Use:

• While reviewing materials gathered during the information collection stage.
• When evaluating the contents of a document, either in development or already existing.
• Deciding on the placement of information within a document’s structure.

Do	Don’t
Place valuable information where it most logically fits or note it for later inclusion.	Include information without assessing its utility in context.
Consult with SMEs to validate the relevance and placement of information if you’re unsure.	Hesitate to exclude information that doesn’t serve the document’s purpose.

Insight

Developing Your Relevance Radar Develop your own “relevance radar” by continuously asking yourself whether the information is necessary for the reader at the current point in the document or even in the document as a whole. If you’re in doubt about a piece of information’s relevance, provisionally include it and seek subject matter expert validation during the next review. Their feedback is crucial in discerning the value of contentious information.

2.2. Key Principle: KISS (Keep It Simple)

The KISS principle, an acronym for “Keep It Simple, Stupid!,” emphasizes the value of simplicity in communication. Originally used in the military to ensure straightforward procedures, this principle is equally important in technical writing. It advocates for writing in a manner that is easily understandable to the average reader, without assuming they have prior knowledge or training. The goal is to make complex information accessible and usable, rather than underestimating your audience’s intelligence. Even experts begin as beginners! The real challenge lies in making your content clear and straightforward so it serves a broad audience.

When to Use:

• In situations where the audience might lack background knowledge.
• To avoid overloading the reader with unnecessary jargon or details.

Assumption to Avoid	Reason
They have received training in the product, process, or procedure.	Many may be new to the topic.
They have been with the company for some time.	New employees might be your audience.
They understand company jargon.	Jargon can be confusing and exclusive.
They want extensive documentation.	Most prefer concise, to-the-point information.
They are familiar with the document’s history and context.	Background knowledge can’t be assumed.
They know where to find supporting tools and documents.	Accessibility of resources varies.

3. [Theory] Organizing Information

In this section, we explore how to structure your writing to enhance clarity and comprehension. We’ll reveal strategies for organizing complex information to ensure your audience can easily navigate and understand your content. By understanding these principles, you’ll learn to create a logical flow that guides your readers through complex technical details with ease.

3.1. Key Principle: Brevity

“I apologize for such a long letter—I didn’t have time to write a short one.”—Mark Twain

Writing clear, concise content takes time and effort, but your readers will thank you. It’s a balancing act: being concise without sacrificing meaning. The principle of brevity isn’t just about using fewer words; it’s about making each word count. The irony is that writing succinctly is often more challenging than filling pages with words. Crafting concise prose is an art that requires writers to distill complex information into easily digestible content. Remember, great writers often spend more time cutting down their work than building it up, ensuring every detail serves a purpose and nothing more.

When to Use:

• In all levels of document creation, from sentences to full sections.
• Especially useful in documents that will be translated, as shorter, clearer sentences reduce translation complexity.

Do	Don’t
Start with longer sentences, then edit down.	Assume the first draft will be anything like the final version.
Aim for sentences averaging 15-20 words.	Create overly short, disconnected sentences.
Break down complex sentences into shorter ones.	Sacrifice clarity for the sake of brevity.

Insight

Reading Effort Is the Inverse of Writing Effort Effort in writing inversely correlates with effort in reading. The more you refine your writing, the easier it is for your audience to understand. This statement reflects the technical writer’s craft, where they make the effort to capture the essence of the material and present the reader with only what is needed. Unfortunately, some people imagine that if a text is easy to read, it was also easy to write, and therefore anyone could do it. This is certainly not the case.

3.2. Key Principle: Chunking

Chunking is an essential technique in technical writing that makes information more accessible and memorable for readers. It involves organizing content into manageable units or “chunks.” This concept is rooted in cognitive psychology, drawing particularly from the work of George A. Miller¹ and, later, Nelson Cowan² who studied the capacity of human short-term memory. Although the exact number of items that constitute an optimal “chunk” varies—Miller suggested seven plus or minus two, while Cowan proposed about four—the principle remains consistent: reduce cognitive load by presenting information in small, digestible segments. This approach is particularly effective when you’re structuring chapters, bulleted lists, or procedural instructions.

When to Use:

• When organizing topics within a chapter to avoid overwhelming the reader.
• For creating bulleted or numbered lists, particularly in procedural contexts.
• During the initial drafting or subsequent review of document structure to ensure information is presented in an easily digestible format.

Do	Don’t
Aim for an average chunk size of 5±2 items.	Overload sections with too much information.
Group related items under a common heading.	Arbitrarily force splits in content merely to stay within the 5±2 items chunk size.
Adapt chunk sizes based on content needs.	Ignore the natural flow of information and its nuanced complexity.

Note

Don’t Force Splits in Content Don’t twist your writing into knots trying to force a split just to satisfy the rule of five plus or minus two items. If a bulleted list contains, say, nine items, or a chapter encompasses eight topics, and there’s no practical way to split these into smaller chunks, don’t worry. Arbitrarily dividing a number of items—by forcing in a heading—can be worse than presenting too many items. There will be plenty of other opportunities to serve your reader by applying the chunking technique!

3.3. Key Principle: Signposting

Signposting involves the use of clear and meaningful headings at various levels within a document. This principle is important because technical documents usually serve as reference materials rather than as texts that are read from beginning to end. Effective signposting allows readers to quickly scan a document to locate the information they need. It requires crafting titles that accurately reflect the content and purpose of the document, its chapters or sections, individual topics, and even specific paragraphs or information blocks. These blocks may include text, tables, or visual elements.

When to Use:

• When titling the entire document to reflect its overall purpose.
• When naming chapters or sections to indicate their specific content and purpose.
• When heading topics within sections to guide the reader to relevant information.
• In concert with verb-noun structure for headings in process-based documentation.
• When labeling paragraphs or information blocks to summarize the enclosed content, whether it’s text, tables, or visual elements.

3.4. Key Principle: Layering

A helpful side effect of signposting is a technique known as layering. Layering enhances navigability and user engagement by structuring content into distinct, hierarchical sections. This method involves using clear headings or titles at various levels of a document to create layers. Each layer represents a specific topic or level of detail. By doing so, readers can easily skim through the document to find the information they need without reading every detail. This approach is especially useful in lengthy or complex documents where users might seek specific information, like a particular procedure or definition.

When to Use:

• In lengthy documents or manuals to enhance readability and navigation.
• When the content includes varied topics or subtopics that can be categorized distinctly.
• In online help systems or digital documents to facilitate efficient search and navigation.
• When the audience is diverse and their needs for information vary in depth and specificity.

Example 1: Layering in a Manual

Context: A printed manual on data management. Layer Structure: • Chapter: “Data Management” • Section: “Archiving” • Topic: “Archiving Client Data” Usage: Allows readers to quickly locate the section on “Archiving” and then drill down to the specific topic of “Archiving Client Data.”

Example 2: Layering in Online Help

Context: An online help system for a software application. Layer Structure: • Searchable Phrase: “Archive client data” • Menu Hierarchy: Home > Help > Data Management > Archiving > Client Data Usage: Users can type “archive client data” in the search box or navigate through help menus to find detailed instructions on the topic.

3.5. Key Principle: Bulleting

Bulleting is a technique employed to enhance the readability and memorability of lists. Unlike sentences that use commas or semicolons to separate items, bulleting presents each item on a new line. This format is visually more appealing and simplifies information processing for the reader. It is particularly effective in technical writing, where clarity and accessibility are of paramount importance.

When to Use:

• Presenting multiple options or values.
• When the list items are distinct and need to be emphasized.
• In situations where quick reference or memorability is essential.

Example: Comma-Separated List	Example: The Same List with Bullet Points
“Our premium holiday rental property has four bedrooms, two bathrooms, a spacious living area, a carport, and a swimming pool.”	“Our premium holiday rental property has: • four bedrooms, • two bathrooms, • a spacious living area, • a carport, and • a swimming pool.”

Do	Don’t
Use a meaningful introductory sentence or phrase before the list.	Repeat the same word at the start of each bullet; reword if necessary.
Use consistent capitalization and punctuation for each item.	Use bullet points if the sequence of items is important; use numbered lists instead.
Keep line lengths similar for visual harmony.	Create a bulleted list for a single item; incorporate it into the sentence instead.
Limit the list to 5-7 items for better reader retention; use sub-headings for longer lists.	Arbitrarily force splits in lists merely to stay within the 5-7 item size.
Use “and” or “or” in the second-to-last item to clarify whether the list is inclusive or exclusive.

4. [Theory] Perfecting Prose

In this section, we aim to refine your writing style for technical documents. You will learn to craft clear, concise, and engaging prose that resonates with your audience. We’ll explore the nuances of language choices, sentence structure, and readability, helping you transform technical jargon into accessible and compelling content.

4.1. Key Principle: Verb-Noun Structure

Verb-noun structure is a straightforward yet effective method for crafting headings, particularly in process and procedure documentation. By placing a verb before a noun, this structure clearly indicates the action and its object, making it easier for readers to understand the purpose of the information that follows. It’s widely used in process modeling and documentation because of its ability to maintain logical consistency and provide a formulaic template for each activity within a process.

For example, in a process model, each activity box named using this method will describe both an action (verb) and the object of that action (noun), thereby eliminating possible ambiguity. This approach also invites questions: Who performed this action (role)? What is the consequence (output) of that action? These questions are essential for the development of fully fleshed-out processes.

When to Use:

• Creating or reviewing headings for processes and procedures.
• Naming activities within a process.
• Developing titles for process-related documentation.

Do	Don’t
Use for headings in process documentation.	Apply to descriptions of concepts or theories.
Follow the formula of verb followed by noun.	Overuse in non-procedural contexts.
Ensure clarity and action-oriented language.	Use for general background information.

Note

Processes vs. Procedures Processes offer a high-level view of the activities needed to achieve a result (such as processing a purchase order), while procedures detail the specific steps for an activity (such as how to raise a purchase order). Understanding this distinction is key to applying the verb-noun structure appropriately.

Note

The Technical Writing Process Uses Verb-Noun Structure You’ve probably noticed that sections of the Technical Writing Process use a verb-noun structure for headings in many chapters. This approach helps us structure the book in tune with its process-oriented nature, making it logical, consistent, and easy for our audience (you) to follow.

4.2. Key Principle: Active Voice

Active voice is a writing technique that focuses attention clearly on the “doer” of an action, making your writing more direct and helping to reduce ambiguity. Unlike passive voice, which can obscure the performer of the action, active voice places the subject at the forefront. Consider: “The designer produced an attractive portfolio,” as opposed to “An attractive portfolio was produced by the designer.” This approach not only clarifies who is doing what but also typically results in shorter, more straightforward sentences. Active voice lends itself naturally to technical writing. It’s especially useful in writing processes or procedures, as it minimizes ambiguity and maintains focus on the subject.

Example: Passive Voice	Example: Active Voice
“An attractive portfolio was produced by the designer.”	“The designer produced an attractive portfolio.”
“Feedback on the project was given by the team leader.”	“The team leader gave feedback on the project.”

When to Use:

• In most technical writing scenarios, especially when describing actions in processes or procedures.
• When clarity about the performer of an action is crucial.
• To achieve conciseness in your writing.

Do	Don’t
Use active voice to highlight the “doer” of an action.	Overuse passive voice, which can obscure the doer.
Use active voice for clarity in process descriptions.	Rely solely on active voice; sometimes passive is appropriate.
Opt for active voice to make sentences more concise.	Forget that in some cases, the doer may be intentionally omitted.

4.3. Key Principle: Imperative Mood

The imperative mood in technical writing is about directness, ensuring that instructions are clear. This mood uses a verb form that conveys a command or request, such as “Click the print button.” This differs from the subjunctive mood, which suggests possibilities (“I would suggest that you click the print button”), and the indicative mood, which states facts or opinions (“You can click the print button if you like”). The imperative mood is about providing clear, direct actions. It’s not about being forceful or rude; rather, it focuses on being helpful and efficient in communication. Technical writing benefits from this direct approach as it guides the reader clearly and reduces ambiguity.

Example: Subjunctive Mood	Example: Indicative Mood	Example: Imperative Mood
“I would suggest that you click the print button.”	“You can click the print button if you like.”	“Click the print button.”
“Consider adjusting the settings for better results.”	“You might want to adjust the settings for better results.”	“Adjust the settings for better results.”

When to Use:

• Writing step-by-step instructions.
• Developing user guides or training materials.
• Any scenario where clear, concise directions are needed.

Do	Don’t
Place the verb at the start of the sentence.	Use overly polite or indirect language.
Use the present tense to imply immediate action.	Add unnecessary words that dilute the directness.

4.4. Key Principle: Parallel Language

Parallel language, also known as parallelism or parallel structure, is a key principle in technical writing that enhances readability and clarity. It involves using the same grammatical structure throughout a sentence, especially in lists or series. This consistency in structure allows readers to follow the text more easily, providing a rhythm and symmetry that make the content more digestible. Applying parallel language is not just about grammatical correctness; it’s about crafting a smooth, cohesive reading experience.

Example: Nonparallel Language	Example: Parallel Language (Gerund Form)	Example: Parallel Language (Infinitive Form)
“My brother likes skydiving, hang-gliding, and to surf.”	“My brother likes skydiving, hang-gliding, and surfing.”	“My brother likes to skydive, to hang-glide, and to surf.”

When to Use:

• When listing items or actions in a sentence.
• In constructing sentences that contain comparisons.
• In bullet points or numbered lists to maintain a uniform structure.
• For headings and subheadings to ensure stylistic consistency.

Do	Don’t
Match the grammatical forms of listed items (all gerunds or all infinitives).	Mix different forms (gerunds with infinitives) in a list.
Apply parallelism in series of actions or descriptions.	Use inconsistent grammatical structures, leading to awkward or confusing sentences.
Use parallel structures in headings and subheadings.	Overlook the need for parallelism in structural elements of your writing.

4.5. Key Principle: Write to the Reader

Writing directly to the reader, known as the second-person narrative style, creates a friendly and engaging tone. This approach makes the reader feel like an active participant in the text. Unlike the first person (“I, me”) or third person (“he, she, they”) perspectives, which tend to be more descriptive and detached, the second person (“you, your”) establishes a direct connection with the reader. It’s particularly effective in technical writing, where clarity and direct instruction are paramount. The second-person narrative is often implicit in procedural language, such as in headings (“[You] Archive client data”) and imperative steps (“[You] Press the Start button”).

Example: First Person Pronouns: I, me, my, myself, we, our	Example: Second Person Pronouns: You, your, yours, yourself, yourselves	Example: Third Person Pronouns: He, him, his, himself, she, her, hers, herself, it, its, itself, they, them, their, theirs, themselves
Text: “I pressed the Start button to start the engine.”	“You must press the Start button to start the engine.”	“He pressed the Start button to start the engine.”

When to Use:

• When providing step-by-step instructions to guide the reader.
• To create a sense of involvement and engagement in the content.
• When a conversational tone is desired to simplify complex information.

1. Miller, G. A. (1956). The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information. Psychological Review, 63(2), 81. ↩︎
2. Cowan, N. (2001). The Magical Number 4 in Short-Term Memory: A Reconsideration of Mental Storage Capacity. Behavioral and Brain Sciences, 24(1), 87-114. ↩︎