Great Technical Writing Process

Do you think that technical writing is hard? Or do you consider anyone can write documentation? Amrute Ranade, a technical writer, thinks that anyone can write but not well. At the same time, tech writing is really hard, and in order to ease the writing process, she developed a methodical multi-step procedure. And I want to describe it for you because it’s really helpful.

Here is her writing workflow for any technical document:

Amrute Ranade’s working process consists of four steps.

Step one: Research

Here are methods she uses at this step:

Cornell note-taking system. It helps to briefly record some key points gathered from read materials, conversations with subject matter experts, and so on. What is the Cornell note-taking system? The Cornell Notes system is a note-taking system that was developed in the 1940s by Walter Pauk, an education professor at Cornell University. Pauk described its use in his book How to Study in College. The method is easy to implement — you should just divide the paper into three columns: main ideas, details and summary. Here is an example, how you can use your notebook.

Feynman technique to summarize the information. The main idea is to tell the information you’ve learnt to other people or you can just imagine that someone is listening to you. The best way is to tell your subject to an 8-year-old kid that will help you not to use difficult words that you’ve just learned by rote. This is an essential step because the main goal of technical writing is to explain clearly to readers how to use a tool or a device. You should keep in mind, users may not have technical education, so they will not understand terms or technical jargon. But if it’s impossible not to use jargon, the article called To Jargon or Not To Jargon in Technical Writing will help you use it in a proper manner.

Then she sets up CockroachDB and tries out the feature or tool that she is going to describe.

Step Two: Draft

At this step, Amrute Ranade uses the 5-draft method:

1. Describe all your ideas on paper or screen.
2. Create a structure of your project
3. Reread your draft and pay attention to the idea. Does it make sense?
4. Ask your friend to read your project and leave you the feedback.
5. Final edit. At the final step of developing a draft, you should remember that you will never have a “final” draft. You will always think that you’ve missed something. Don’t give up because you’re closer to the end of the project.

“Art is never finished, only abandoned.”

~Leonardo da Vinci

Step 3: Editing and Reviews

When she has finished her rough draft, she uses several techniques:

• Grammarly — to check grammar mistakes.
• Text-to-speech — to listen to the document. It helps to edit sentence structures, add missing words, and so on.
• Elements of style: books that remind Amrute Ranade her mistakes and help her not to repeat them.
• Style guide: A style guide of a company to adhere to it.

When she’s done with editing, she opens a pull request on GitHub which enables other experts to review her document. Engineers, product managers, and other staff of the company read the document and leave their feedback.

The Final Step: Publish

After the final editing, it’s time to merge the document on GitHub. Also, she usually tracks each step in the bullet journal.

Do you use any of these methods while developing documentation? Please, share in comments!

Technical Writing Blog

How did I become a technical writer? What skills do you need? Read FAQ on Technical Writing.

FAQ on Technical Writing