Lead Writers: Steve Moss, Kieran Morgan | Managing Editor: Kieran Morgan
This chapter guides technical writers through the drafting stage. It introduces the iterative nature of writing, emphasizing the interplay between the writer, subject matter experts, and the product, process, or software system being documented. The chapter covers theoretical aspects by outlining key drafting stages, the write-review-update cycle, and the nuts and bolts of establishing version control. Practically, it instructs on preparing and writing the first draft, and engaging with subject matter experts through interviews and workshops.
 Who Should Read This | |
| • Aspiring Technical Writers • Beginner Technical Writers • Cross-Domain Professionals | |
| Table of Contents: Technical Writing Process | |
| Previous: Chapter 16: Writing Principles | Next: Chapter 18: Include Images |
Table of Contents
1. Introduction
“Writing is easy. You just open a vein and bleed.”—Unknown Author1
This dramatic statement, often attributed to various authors, captures a certain truth about the emotional labor involved in crafting a piece of writing. However, when it comes to technical documentation, the process is less about emotional outpour and more about methodical precision.
We’ve spent ample time discussing preparation; now, let’s dive into the act of writing itself. Writing is an iterative cycle of drafting, reviewing, editing, and polishing—and then doing it all over again, until your document is just right. This stage, writing the draft, is where you transform your detailed planning, collected information, and document structure (also known as the table of contents) into a series of drafts.
In this chapter, we focus on several related concepts: the stages of drafting, the write-review-update cycle, and establishing version control. We then conclude with practical steps for starting your first draft and templates to assist you in conducting subject matter interviews and workshops—essential steps in your preparation for writing.
If your documentation needs to include images, such as screenshots, photographs, or diagrams, and you’re unsure about best practices, check out Chapter 20: Include Images.
2. [Theory] The Stages of Drafting: First, Interim, and Final Drafts
It’s rare for a perfect first draft to emerge. In practice, most documents are written, reviewed, tested, and revised multiple times. This may seem like a waste of time for those new to writing, but it’s an essential part of the process. The repeated cycles of review and revision improve your document’s technical accuracy, enhance the quality and clarity of the writing, address gaps and weak spots, and allow for enhancements and updates.
Documents usually go through three stages of drafts—first draft, interim (or working) drafts, and final draft, as shown in the diagram below. This chapter focuses on the first draft stage. The following chapters, Chapter 21: Edit Drafts and Chapter 22: Review Draft, discuss the steps required to progress from a first draft to an interim and then a final draft, ready for approval and publication.
3. [Theory] The Write-Review-Update Cycle
Writing and reviewing is a highly iterative process. Drafts may go through any number of cycles of reviewing and updating until the final draft is ready for approval. The number of cycles, and their timing and duration, will be influenced by a smorgasbord of factors—the complexity of the subject matter, your experience and skill as a technical writer, the availability of reviewers, and more. Writing isn’t an exact science!
The accompanying diagram depicts the cyclical nature of the write-review-update cycle. As you can see, it’s the “Interim Draft” stage that introduces this uncertainty. This highly iterative phase, involving multiple cycles of review and update, is an unavoidable part of the process. No matter how good your first draft, it will always benefit from refinement by review. We discuss review in detail in Chapter 22: Review Draft.
Editing is your constant companion at every stage in drafting. Every time you write or update a draft, no matter what stage, it should always be edited—although the level of rigor in your editing will differ as you progress from the first through to the final draft, as we explain in Chapter 21: Edit Drafts. The cycle ends when the final draft is edited, proofed, and ready for approval.
 Insight |
| Refining Words: Honing, Polishing, and… Sanding?! Refining words is a craft akin to carpentry. Just as a carpenter sands down rough edges to reveal the smooth surface beneath, a writer continually hones and polishes their prose. This isn’t the same as editing; it’s a more subtle, continuous process of enhancement. With practice, this skill becomes second nature, integral to the act of writing itself. |
4. [Theory] Version Control
Version control is the process of tracking and managing documentation as it’s updated. It puts you in the conductor’s seat, enabling you to orchestrate the write-review-update cycle and keeping what can be a complex process manageable. It’s all part of the good housekeeping that any good technical writer should practice—and may be required under your organization’s policies or standards such as ISO 9001.
Version control is often done automatically by content management systems. If not, there’s a simple, tried-and-trusted system used by technical writers and knowledge workers alike: the version (or “revision”) number system.2
This method works by appending a numerical version number at the end of the document filename after every update, as shown in the diagram below. It’s particularly helpful when the write-review-update process occurs via email, necessitating strict version control by the writer.
 What Does That Mean? |
| ISO 9001 ISO 9001 is the global standard for quality management systems. It’s published by the International Organization for Standardization, a nongovernmental organization that develops international standards across a wide range of industries and sectors. This standard focuses on ensuring companies meet customer needs for their products and services. It also sets out requirements for document control, which we discuss in depth in Chapter 26: Publish. Version • Meaning 1: The specific identifier assigned to a document each time it is updated. This versioning allows for tracking the evolution of a document, as different versions (or “revisions”) represent the document at various stages of its editing history. • Meaning 2: A document’s adaptation for different user groups while maintaining the same core content. For example, the same procedure document could exist in two versions: one in English and another in Spanish. Version Control A systematic process for tracking and managing different iterations of a document as it is revised and updated over time. This process ensures that all changes made to a document are recorded, enabling an audit trail of its evolution. |
 Tip |
| Implementing Version Control for Uncontrolled Content Effective version control can be challenging to implement when developing topics in systems not designed for it. Topics may be reviewed in an online platform or a source code repository, which may not support the nuanced review cycle described here. In such cases, it might be practical to export online topics into Google Docs or Microsoft Word documents. This allows them to be tracked during the write-review-update process. However, this approach can lead to some messy housekeeping when it’s time to update the content online at the conclusion of the review cycle. |
5. [Practice] Write First Draft
You’re now standing at the threshold of writing the first draft. This stage is where your planning and information gathering pay off. This section guides you through transforming your plans and research into a coherent, structured first draft that lays the foundation for what will eventually be a polished and professional document.
The main inputs for this stage are the information you collected in Part 4: Plan and the draft document structure (also known as the table of contents) you developed in Part 5: Design. As you write, you’ll be guided by the knowledge of the purpose and audience of your document, which you defined when you wrote your Documentation Plan (see Chapter 10: Make a Plan). With every sentence you write, you’ll apply the writing principles you learned in Chapter 18: Writing Principles.
This section guides you through the process of taking those inputs and developing that critical first draft.
5.1. Step 1: Choose a Topic to Write
Select a topic from your document structure that you mapped out in Chapter 15: Design Structure. It’s best to choose a topic that you have plenty of information on already. This will allow you to quickly make good progress. The topic may be a high-priority task or one that you are familiar with from experimenting with the product.
5.2. Step 2: Prepare
Before writing the first draft, preparation is key. It’s about gathering the information you need to construct a comprehensive and accurate first draft for the topic you’re going to focus on initially. You should already have the background information you gathered in Chapter 9: Collect Information. This section is about bringing together the specific information you need to write your chosen topic.
Here are some common techniques technical writers use to prepare:
- Engage with subject matter experts. Interviewing subject matter experts is an essential part of the preparation process. It involves detailed discussions, notetaking, and capturing screenshots where necessary. Early in the project, you might set up a series of meetings to progressively develop the document’s content. When dealing with multiple subject matter experts on the same topic, workshops can be an efficient way to collect all their input simultaneously. We’ll cover more on this in the following section.
- Apply your knowledge. If you’re writing about a product you’re familiar with—or are becoming familiar with through experimentation—you can use your knowledge to draft the document. Get hands-on with the product in a testing environment, such as a sandbox for software, to understand it better. This hands-on testing has the benefit of enabling you to personally verify the procedures you’re writing about. This is critical for developing accurate procedures.
- Use legacy documentation. Start with what’s already there. Existing documents can serve as a starting point for your new content. Depending on their quality, you might only need to update or edit parts of them. If they’re outdated or inaccurate, you could be looking at a full rewrite. Be cautious with old material; sometimes it can lead to more issues than it solves. However, don’t ignore potentially useful bits of knowledge tucked away in previous documents.
- Delegate writing tasks to others. Getting others to write content for you can save time on internal documentation projects, especially when the writers are few—or just you!—and the scope is large. In some projects, writers act as both project manager and editor to a group of subject matter experts, assigning topics to the experts. If that’s you, provide them with clear templates and well-written examples to guide their writing. Keep track of progress with a Status Tracker Template or Sample Documentation Project Schedule to ensure timely delivery, and be ready to send out reminders to keep everyone on track.
5.3. Step 3: Engage with Subject Matter Experts
In most documentation projects, your primary port of call for collecting information is subject matter experts. This is where you gain firsthand knowledge from those who know it best. You’ll interview them, take notes, or perhaps even document as you go, capturing screenshots and noting down the sequence of steps on the fly. This information is a direct input, if not the source material, for your first draft. In this section, we’ll discuss the two main approaches for engaging with subject matter experts: interviews and workshops.
5.3.1. Interviews
Interviews—either face-to-face or online—are a staple in the technical writer’s toolkit. They’re an excellent way of collecting information firsthand, whether it’s about a product, service, or process. Good interviews don’t just help you create accurate, high-quality documentation—they also help build rapport with colleagues.
Our Subject Matter Expert Interview Template explains how to prepare for the interview, including timing and duration, questions to ask, and a suggested sequence.
When to Use:
- Exploring complex topics. Interviews are ideal for unpacking complex or technical subjects, such as explaining a complex feature, validating the exact sequence of steps in a procedure, or capturing screenshots as a sequence of steps is demonstrated in a software application.
| Insight |
| Use AI to Save Time in Notetaking and Transcribing To save time, consider using AI tools such as ChatGPT to convert your rough notes into properly formatted minutes and actions. For more information on how to do so, see Chapter 8: Artificial Intelligence (AI) for Technical Writers. If a transcription of a recording is necessary and this functionality isn’t built into your collaboration software, consider sending a recording to a transcription service such as Rev AI Speech to Text Transcription Service. Before you record, make sure to ask your subject matter expert for permission to do so. |
5.3.2. Workshops
Workshops—either face-to-face or online—are an excellent way of gathering information from multiple subject matter experts simultaneously in a group setting. In a workshop, you’ll play the role of facilitator, ensuring that each subject matter expert gets an opportunity to contribute and that discussions stay on point.
Our Subject Matter Expert (SME) Workshop Template explains how to prepare for a productive workshop, including timing and duration, questions to ask, and a suggested sequence.
When to Use:
- Structuring and planning. When reviewing draft structures (tables of contents, lists of topics, and so on) for documentation or brainstorming which deliverables are required for a new project.
- Getting consensus on processes or procedures. When reviewing processes or procedures, typically where there’s some confusion about the correct sequence or a process hasn’t been fully mapped out yet.
Never try to finesse the wording of documents in a workshop. People will spend hours agonizing over a single sentence given the chance!
| Tip |
| Building Bridges: The Art of Collaborating Building strong relationships with subject matter experts is important for both your work and your career. A good rapport leads to better access, quality feedback, and improved documentation. For subject matter experts, it ensures their work is understood and supported throughout the development process. To foster these relationships, writers should engage as full participants in the process by attending and contributing to meetings, respect subject matter experts’ time by being accommodating, and offer help and insights to avoid a one-sided dynamic where the writer only takes information without contributing anything of value in return. Remember, effective collaboration is about creating a win-win outcome. When done right, it will expand your professional network with an ever-growing group of professionals who hold you in high esteem—and may well open up future job opportunities as time goes by. |
5.4. Step 4: Start Writing
Now it’s time to write. As technical documentation is usually task-focused, a good place to start is by writing the procedural steps. That will lead you to other information that you’ll need to complete the topic. This may include concepts necessary to understand the task, specific tools required to execute it, or other topics that are downstream or upstream of it. You may also find that there are “what ifs”—conditional steps that need to be included, such as a failure mode that needs documenting or cross-references to troubleshooting topics.
As you work through your notes and incorporate them into your draft, you’ll come across chunks of information that you’ll want to include—enough for a sentence, table, diagram, paragraph, or perhaps more. Add these chunks into your draft, integrating them into the structure so that they don’t interrupt the flow.
In your notes, keep track of information that you have already incorporated by marking it, for example, with strikethrough or a different color. This “mosaic” approach will let you integrate information from your notes into your draft structure without causing duplication—which you want to avoid.
| Tip |
| Write Introductions and Overviews Last Although they always appear first in the table of contents, don’t write introductions or overviews first. You won’t have the necessary knowledge of the product, feature, or process at this stage. Only as you close in on the final draft stage will you have built your knowledge to the point where you can finally write the overview. To save time, you can use AI to help you do so—see Chapter 8: Artificial Intelligence (AI) for Technical Writers. |
| Insight |
| For a Fresh Perspective, Sleep on It After completing your first draft, set it aside for a day or two before revisiting it. This pause allows you to gain a fresh perspective on what you’ve written. When you return to your draft, you may discover that details previously overlooked now leap out at you, enabling you to easily identify areas that need refinement or clarification. |
5.5. Step 5: Update Structure
As you write, you’ll discover that your document’s structure will evolve. This is completely normal—it’s the result of building your knowledge about whatever you’re documenting, knowledge you didn’t have at the start of your project. Even a technical writer with deep knowledge of the subject will find that things evolve in ways they hadn’t anticipated as they progress. No one has perfect knowledge!
Don’t be surprised if you find that:
- Topics blow out into chapters—and chapters condense into topics.
- New topics are discovered that need to be added to chapters.
- New chapters are required to encompass topics you hadn’t considered originally.
- The ordering of information in the document structure has changed.
- Appendices are now required for reference material.
5.6. Step 6: Edit Draft
Finally, you’ll need to edit your first draft so that it’s polished enough for a subject matter expert review. Although your first draft doesn’t need to be perfect—and may contain things such as placeholders for information you haven’t yet gathered—you don’t want to send out a draft full of obvious mistakes in spelling, grammar, and punctuation. While it may save time, it could lead others to question your writing skills and your attention to detail.
In the next chapter, Chapter 21: Edit Drafts, we focus on the editing process and explain how to apply the appropriate level of editing to refine your document at the different stages of the write-review-update cycle.
6. [Template] Subject Matter Expert Interview Template
Subject Matter Expert Interview Template