If I had a dollar for every time someone has 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 is to follow a technical writing process.

Technical writing — just like every other creative process — is difficult, especially when you're writing about something new and unfamiliar (which is probably what you'll be doing most of the time as a technical writer). Even 'natural born' writers will struggle without a writing process.

A writing process breaks the intimidating task of "TECHNICAL WRITING" into distinct steps that you can check off one by one to encourage the creation of content in a systematic way.

Good writing requires planning and preparation. Based on my experience creating technical content (technical articles and documentation) for some startups, I'll share the same process I follow to write high-quality technical content consistently. This will help you overcome the initial blank-page confusion, so you can also start writing better technical content (whether in a personal or professional setting) with speed and ease.

1. Define your audience
2. Define the goal of the content
3. Write an outline
4. Do your research
5. Write the first draft
6. Rewrite the first draft
7. Fine-tune and polish
8. Ask for feedback
9. Publish and share

N.B: This technical writing process article does not cover how to generate topic ideas or decide what to write. It assumes that have what to write about. It also does not place much emphasis on grammar rules because they are secondary. Instead, it focuses on a series of high-level steps that you can follow to give direction and purpose to your writing and make the task less daunting.

Stage 1 of the technical writing process: Prewriting

Prewriting refers to everything you do before writing an actual draft. Prewriting is the stage in the technical writing process in which you define the direction and strategy for the content you're about to write.

Do these prewriting tasks well, and writing the draft will be a breeze.

1. Define your audience

To create effective content (i.e, content that will be useful to your audience), you need to understand who they are. When you understand your audience, you'd be able to write content that resonates with, impacts, and offers them a better reading experience.

To define your audience, ask yourself: Who am I writing this piece of content for? Are they beginner developers, mid-level developers, product managers, designers, etc?

Your intended audience determines the tone you should lean on while writing, the level of background information you need to provide, the frequency with which you define terminology, what you should cover and shouldn't, and the overall direction of the content.

For example, say you're writing an article on how to build a demo CRM with React, which will require connecting a database (SQL or otherwise). If your intended audience are frontend developers with no idea of databases or SQL, you'll need to have a section introducing them to the basics of SQL databases and how they work, and maybe a link to go read up on SQL commands.

However, if your audience are core back-end developers, you'll need to have a section introducing them to React and how it works.

2. Define the goal of your technical content

Every piece of content you write should have a goal; otherwise, you'll write something that doesn't deliver any value because your points will be all over the place. Just like defining your audience, defining the goal of every piece of content helps provide you with more direction and focus.

The goal of every piece of content can be thought of in two parts: the producer's goal and the readers' goal.

The producer's goal

A producer is someone or a group of persons who wants to write a piece of content. In this case, the producer is you (an individual technical writer writing for yourself, or the company paying for you).

Defining the producer's goal helps you understand why you or your company has decided to write a particular piece of content. Without specifying this goal, you're less likely to care about what you're writing. And, when you don't care about what you're writing, you're less likely to deliver value.

To define your producer goals, ask yourself these questions:

• "As a person, why do I want to write this piece of content?"
• "As a company, why should we produce this piece of content?"

An example of a producer's goal could be:

• "I am writing this article to showcase my understanding of a particular subject matter and encourage people to sign up to 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)

The readers' goal

The readers' goal is why your audience should care about your content or even read it. When users search for content, their goal is usually to either get a solution to a pain point or find answers to a pressing question.

To understand your readers' goal, ask yourself:

• "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 are looking for answers to?"

As much as your goals are important, that of your audience is more important. It is only when you create value for your audience that they will convert (i.e help you achieve your own goal). So, you need to marry your goals to that of your audience, to achieve better results.

For example, the producer's goals arrived at in the preceding section can be reframed to these below, which puts the reader into consideration:

• "Frontend developers struggle with understanding the concept of React context. I will use the analogy of driving a car to break down the concept and make it more relatable. This will showcase my deep understanding of the concept, and then I will encourage readers to sign up for my newsletter for similar content."
• "Setting up public APIs is always a tedious task for developers because of the numerous steps involved. This piece of content will show developers how they can use our product to set up public APIs in just 3 steps. This should encourage them to start using it"

After you arrive at the combined goal, write it down. That way, you'll be able to cross-check your writing with it, in the end, to confirm that you were able to deliver on your goal.

3. Write an outline

An outline is like a map that guides you to a destination — without which you'll end up missing your way.

An outline can be described as the barebones structure of your content. It allows you to narrow down your ideas to the main points that you need to cover, ensuring that you deliver on the goal of that specific piece of content without deviating.

An outline typically contains:

• A title
• A thesis (the primary point of the article), and
• Headings and sub-headings representing the points you'll need to cover to deliver on your content goal.

How to come up with a title for your technical documents

Every piece of content should have a title that summarizes it's value proposition.

Most of the time, I use the template below to generate 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'. Anyone who sees the title will immediately understand what they're getting and who it's written for. This makes it easier for your target audience to identify with your content, among others.

How to come up with a thesis for your technical documents

After defining the title, define the thesis or the main point of the content. The thesis is the main message that a piece of content attempts to convey, and it is usually closely related to the goal you defined in the previous section.

For example, following the public API article example, the thesis could be:

"No developer should be subjected to spending an ungodly amount of hours setting up public APIs. Our tool makes setting up public APIs as easy as three lines of code, so developers can channel that time to do more impactful work".

How to establish headings and points to guide the structure of your technical documents

After you've defined your thesis and content goal, the next thing is to construct the body's structure.

Consider all the significant points you'll need to cover to deliver on both your content goal and on your thesis. Then, write them down as headers.

If the goal is to explain a technical concept, list all of the components that comprise that concept. If it is a step-by-step guide for completing a specific task, list all necessary steps. Then, under each major heading, fill in the sub-points or sub-tasks that you'll need to address as well.

For example, my outline for this article could look like so:

4. Do your research

Research is a vital step in writing. So crucial that I'd like to say that a successful piece of writing depends on 60% research, 10% writing, 10% editing, and 20% distribution.

Research is a continuous process when writing. From the moment you decide what to write on, to defining your target audience, to drawing up an outline, you must conduct research to gain perspective. The level of research you do will reflect on how confident you'll feel about writing that particular piece of content.

So after you've drawn up an outline, do some research and read up on existing similar or related content to gain more understanding and authority over the topic. If you need to build out a demo app or write some code, this would also be a good time to do that.

Stage 2 of the technical writing process: Time to write

After defining the basic structure and direction and reading up on helpful information, it's time to start writing.

1. Write the first draft.

The goal of the first draft is to help you get all of the ideas in your head onto paper (within the constraints of your outline and target audience, of course). Write down all of the ideas that come to you in relation to your outline. It doesn't have to look good or even be moderately ready for publishing. Write, then fix later.

While writing out this draft, you may likely get stuck on some areas. That's perfectly normal. This might indicate that you need to stop and go do more research or consult someone knowledgeable about the topic. Alternatively, mark the section that needs to be worked on as Todo and continue writing the sections that you flow freely to you.

2. Rewrite the first draft

The goal of this rewrite is to organize all of the ideas that were jumbled together in your first draft into a coherent and presentable format.

In this phase, you should arrange paragraphs and sentences one after the other to achieve flow and remove any awkward phrases or duplicate information. It would help if you also wrote a proper intro and outro.

Your intro should answer the question: "Will this help me?, Should I be reading this?". It needs to contain the goal of the content (what the user will learn from the content), and any prerequisites knowledge they need to have.

In contrast, your outro should include the next steps for the reader (what should they do next after reading your article). This can include anything from relevant links to additional resources.

Asides that, here's a list of other things to do in the rewrite phase:

• Rewrite every paragraph and section with the key ideas positioned first, to promote readability.
• Remove anything that doesn't support your main point or will distract from key points.
• Verify that there are no gaps in your writing and that you've provided all the information the reader needs to arrive at the goal set out at the beginning.

Typically I'd say put some distance between your first draft and every rewrite. If you can afford the luxury of time, the next day is best. This allows you to have a fresh perspective and brain.

3. Fine-tune and polish

Now, this is the stage where you read through your more polished writing sentence by sentence and try to clean it up even more. Unlike the rewriting, which is more concerned with high-level coherence, this phase is about minute tweaks.

Here's a checklist of some things to do at this stage:

• Remove awkward phrases or ambiguous words that may make it hard for the reader to understand the content.
• Make sure all links work
• Create smooth transitions between paragraphs and sentences.
• Run content through a grammar checker like Grammarly
• Run a plagiarism check using a tool like Grammarly or Unicheck.
• Break down longer sentences of more than 25 words into two.
• Break paragraphs into a maximum span of 6 lines.
• Clean out your subheaders. Make them as brief and as clear as possible.

Stage 3 of the technical writing process: After writing…

Now that you're done with writing, it's time to ask for feedback and get it ready for publishing.

1. Ask for feedback

You can either stop at the fine-tuning stage and move on to the publishing phase, or ask for feedback from an extra pair of eyes (like a friend) if you're writing for yourself.

If you're working in a professional setting, you'd usually send this to your clients or superiors for feedback and then try to incorporate their suggestions.

2. Publish and share

After you've incorporated feedback, it's now time to publish. You'd typically 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 so other people can see it.

What's the essence of writing if no one ever sees it?

Take care not to get stuck on the editing and polishing loop. The thing about technical writing is that there will always be room for more tweaking, some more editing, or something you can do to make it better. But do that, and you'll never finish.

As Leonardo da Vinci said: "Art is never finished but abandoned". Set a deadline, stick to it, and consider it done.

Good writing is a skill and can be developed

Writing well is a skill that can be honed with enough practice and time. I hope the technical writing process discussed above has provided you with a framework to get better at technical writing. However, consider it merely a suggestion. You're free to tweak it and rearrange it as you see fit until you find something that works for you. There is no "right way" or "wrong way" to write, but having a defined technical writing process makes it easier.12.1 3