If I had a dollar for every time someone asked me, “I am not a natural-born writer, how can I get better at technical writing?”, I’d probably own a private jet.
My answer to this question is straightforward: follow a technical writing process.
Technical writing, like any other creative process, is tough, especially when writing about something new and unfamiliar, which is often the case for technical writers. Even ‘natural born’ writers will struggle without a system in place.
A writing process breaks down the task of “TECHNICAL WRITING” into manageable steps that can be ticked off one by one, making it easier to create content systematically.
Effective writing requires planning and preparation. Based on my experience creating technical content for various startups, including technical articles and documentation, I will share the same process I follow to consistently write high-quality technical content. This process will help you overcome the initial confusion that comes with starting a document, so that you can start writing better technical content with speed and ease, both at a personal and professional level.
Step 1 – Prewriting:
Prewriting refers to the essential tasks done before writing the draft, which defines the direction and strategy for the technical content you are about to create.
1. Define your audience:
To create great content that will be useful to your target audience, you must understand their needs and interests. Analyzing your audience will help you write content that resonates with them and provides them with an excellent reading experience.
To define your audience, ask yourself questions like: Who am I writing this content for? Are they beginner developers, mid-level developers, product managers, designers, etc.?
Your audience’s characteristics should guide the tone of your content, the level of background information you need to provide, how frequently you define technical terms, what you include, what you exclude, and overall direction.
For instance, if you’re writing an article on how to build a demo CRM with React, which requires connecting a database, if your intended audience is frontend developers with no understanding of databases or SQL, you need to present an introductory section on the basics of SQL databases and how they work, just to mention a few.
2. Define the goal of your technical content:
Every piece of content you create should have a specific goal to accomplish; otherwise, the point will be all over the place. Defining the goal of the content will help you focus and give direction.
The goal of the content can be divided into two parts: producer’s goal and reader’s goal.
Producer’s goal:
A producer could be an individual technical writer or a company that wants to publish a specific piece of content. Defining the producer’s goal will make you understand why you choose to create that specific content. Without specifying your goal, it’ll be difficult to care about what you’re writing, resulting in delivering low value.
To define your producer’s goals, ask yourself these questions:
-Why do I want to write this piece of content?
-Why should my company produce this piece of content?
An example of a producer’s goal could be:
“I am writing this article to exhibit my understanding of a particular subject matter and encourage people to sign up for my newsletter or follow me on Twitter” (personal).
“We’re creating this piece of content to drive more awareness for our product and encourage people to use it or download it” (company).
Reader’s goal:
The reader’s goal is why your audience should care about your content or even read it in the first place. Users seek content to find solutions to pain points or answers to pressing questions.
To understand your reader’s goal, ask yourself questions such as:
“What are the pain points of my target audience regarding this particular topic?”
“Regarding this particular topic, what are the pressing questions that my audience is looking for answers to?”
As much as your goals are essential, your audience’s goal is MORE important. You need to match your goals to that of your audience to create valuable content that will make them convert, resulting in achieving your set goals.
For example, working with the goals arrived at in the previous section, reframing them to consider the reader:
“Frontend developers face challenges with understanding the concept of React context. I will use the analogy of driving a car to explain the concept and make it more relatable. This will demonstrate my understanding of the concept, and I can encourage readers to sign up for my newsletter for similar content.”
“Setting up public APIs is always a time-consuming task for developers due to the multiple steps involved. This article will demonstrate how developers can use our product to set up public APIs in only three steps. This should encourage them to start using the product.”
Once you’ve defined the combined goal, note it down. That way, you can check your writing against it to ensure that you’ve delivered the anticipated results.
3. Write an Outline:
An outline is a guiding map to your destination, without which you may end up going astray.
An outline is a skeletal framework for your content. It narrows down your ideas to the essential points that you need to cover to achieve the content’s goals without straying off the intended path.
An outline typically includes:
-A title
-A thesis (the primary point of the article)
-Headings and subheadings representing the significant points you need to address to achieve the content’s objectives.
How to structure titles for technical documents:
Every piece of content should have a title that summarizes its value proposition.
Most times, I use the following template to create article or documentation titles:
[goal or end result] for [target audience].
For example, ‘How to Set Up Public APIs in 3 Easy Steps for Developers Who Hate Stress’. The title immediately gives a summary of the content’s purpose and intended audience, making it easier for your target audience to identify with your content.
How to structure the thesis statement for technical documents:
After defining the title, the next thing is to create the thesis statement or the primary idea you want to convey. The thesis statement should closely relate to the goal you decided on in the previous section.
For example, following the public API article example, the thesis statement could be:
“No developer should spend hours setting up public APIs. Our tool makes it possible to set up public APIs with just three lines of code, thus enabling developers to focus on more impactful work.”
How to structure headings and points to guide the structure of technical documents:
After defining your thesis and content goal, the next thing is to structure the body of the document.
Consider all the significant points you need to cover to accomplish both your content goals and your thesis statement. Write these down as headings. If the goal is to explain a technical concept, list all the components that make up the idea. If it is a step-by-step guide for completing a specific task, list all the necessary steps. After that, under every major heading, add the corresponding subpoints or steps to be dealt with.
For example, outlining for this article could be:
Step 2 – Writing:
After defining the general structure and direction to follow and reading up on useful material, it’s time to start writing.
1. Write the first draft:
The aim of the first draft is to jot down all the ideas you have in your head on paper (within the confines of your outline and target audience, of course). Write down all the points related to your outline. It doesn’t need to be in an excellent publishing state, or anything of the sort, write freely in this stage.
While writing the first draft, you’ll probably encounter some snags. It’s alright! It might indicate that you require additional research or expert help on that topic. Alternatively, mark the section that needs work as Todo and continue writing the sections where the words keep flowing easily.
2. Rewrite the first draft:
The goal of this stage is to reorganize the initial draft’s scattered ideas into a clear, coherent and presentable format.
In this stage, you should arrange the paragraphs and sentences in a logical and easy to read manner. You should also write a proper introduction and conclusion.
Your introduction should answer the question: “Does this help me? Should I be reading this?” It should include the goal of the content (what the user will gain from the content) and any prerequisites to have access to the knowledge in the document.
Conversely, your outro should outline the next steps for the reader after going through your article. This might include any relevant links or additional resources.
Aside from the above, here’s a list of other things to do in the rewrite phase:
-Rewrite every paragraph and section with the principal points positioned first to boost readability.
-Remove anything distracting, not supportive of your main idea, or repetitious.
-Verify that there are no gaps in your writing and that you’ve provided all the information the reader needs to get to the goal set out from the beginning.
-In general, I’d advise that you put some distance between your first draft and rewriting (if time permits- next day is best). This ensures you have fresh eyes and perspective.
3. Fine-tune and polish:
This is the stage where you read through your rewritten content sentence by sentence, attempting to clean it up even more. In this phase, the focus is on tiny adjustments.
Here is a checklist of some things to do at this stage:
-Remove confusing phrases or ambiguous words that may make it hard for the reader to understand the content.
-Make sure all links are active.
-Improve transitions between paragraphs and sentences.
-Use a grammar checker like Grammarly.
-Use plagiarism checker tools like Grammarly or Unicheck.
-Break longer sentences of 25 words or more into two.
-Break paragraphs into a maximum of six lines.
-Simplify your sub-headers. Make them brief and transparent.
Step 3 – After Writing:
Now that writing is done, it’s time to get feedback and ready the content for publishing.
1. Ask for Feedback:
You could either stop at the polishing stage and proceed straight to the publication phase or ask for feedback from an extra pair of eyes (like a friend) if you’re writing for yourself.
In a professional setting, you’d typically send the content for feedback to clients or superiors, attempt to incorporate their suggestions, then proceed with publishing.
After incorporating relevant feedback, it’s time to publish. Transfer the content from your drafting location (google doc, dropbox, e.t.c) to the publishing medium (code editor, markdown files, CMS) then share the excellent content you’ve written to social media.
What’s the point of creating content if no one ever sees it?
Take care not to dwell too long on the editing and formatting loop. One of the advantages of technical writing is that there is always room for more polishing, editing, or content improvement. But if you keep tweaking, you may never finish.
As Leonardo da Vinci said: “Art is never finished but abandoned.” Set a deadline for yourself, stick to it, and consider it done.
Writing is a skill that can be improved with practice:
Writing well is not a talent that some are born with; it’s a skill that develops with enough time and practice. I hope that the technical writing process presented here provides you with a framework to enhance your technical writing. However, treat this as a guide, and shape it to meet your specific needs. There is no “right way” or “wrong way” to write, but having a defined technical writing process makes it easier to create excellent technical content.