As an engineer-turned-tech writer, I have repeatedly heard “Writing is so hard; how do you do it?” and “Anyone can write”. Both statements are fallacious. Yes, anyone can write, but not everyone can write well. And yes, writing is hard, and it is made harder by the romanticized notions of inspiration striking, wooden cabins in the middle of nowhere, and solitude.
In reality, writing is a methodical, multi-step process. In this blog post, I attempt to break down my technical writing process so as to demystify it and hopefully make you think about your own process. The following image depicts my writing workflow for any technical document:
As the image shows, my writing workflow consists of four phases:
Phase One: Research
My research phase consists of the following steps.
- Use the Cornell Note-taking System to briefly record the key points gathered from sources (reading materials, talking to engineers, attending meetings, and so on).
- Use the Feynman technique to ensure that you understand the information.
- Setup CockroachDB.
- Try out the feature being written about.
Phase Two: Draft
I use the 5-draft method while writing documents.
Phase Three: Editing and Reviews
Once I am satisfied with the rough draft, I edit my document using several techniques. Each technique helps uncover and correct different facets of the document:
- Grammarly: Check spelling, grammar, adherence to technical writing conventions
- Text-to-speech: I use the text-to-speech feature on my Macbook Pro to listen to the document. It helps me catch awkward sentence constructions, missing words, and so on.
- Elements of Style: This little book sits on my desk and reminds me of my personal pitfalls/repeated mistakes. I have earmarked the style guidelines that I know I forget. Going through the book helps me ensure I am not repeating my mistakes.
- Style guide: I go through the company style guide to ensure I adhered to it.
Once I am done self-editing, I open a Pull Request in GitHub which enables others to review my document. My review process is iterative, wherein my draft goes through technical and editorial reviews multiple times before it can be published. At Cockroach Labs, our engineers and other stakeholders (Product Managers, Sales, etc.) review the document for technical accuracy and completeness, and my manager and fellow technical writers review the document for editorial as well as technical completeness and correctness. The perks of working at a company that is deeply interested in good documentation 🙂
Phase Four: Publish
Once the reviews are done and everyone gives the LGTM (Looks Good To Me), it’s time to merge the document on GitHub and celebrate! Check out my Git profile here.
Try out the process, form your own, and share it with me at hello@amrutaranade.com. And don’t forget to subscribe!
Bonus: I track the various phases of each document in my bullet journal:
Thanks for this informative article, Amruta! I will follow few of your good practices from now on. 🙂
Glad you found it helpful 🙂
Thanks for the information! I really enjoy reading your blog =)
Thank you! I am so glad you enjoy it..And keep the feedback coming 🙂
Thank you for responding to me! Right now, I’m trying to be a technical writer, so I enjoy reading and learning about the field.
Thank you so much for this!
Really your article on Writing process was very useful and informative. Thank you! 🙂
Very well written article and useful. Thanks for taking the time to write in such detail.
Thanks for this wonderful article! But, could you help me with something? When I am writing I never know when to stop researching and because of that I never post… How do you know when to stop researching? Better: How do you know that you went deep enough on a topic and it is time to stop researching and start drafting?
Thanks very much again!
Hi Rafael! I am in the same boat as yours – too much research can indeed lead to analysis-paralysis and keep me from writing. One way I have found to avoid that is to start with the end in mind and work backwards. This is easier for me to do because I work mostly on feature docs, so I know what my user needs to know and I can limit my research and content to the users’ requirements. Another way is to use the Feynman technique – I do a primary round of research and then explain the concept to myself, then read some more to fill in the gaps in my understanding. Breaking up the research cycle helps me be mindful of getting just enough information without getting stuck. Does this answer your question?
Thanks very much for your time, it was very helpful!
Why is step 3 of phase one always to setup CockroachDB?
Because I am a technical writer at CockroachDB..so to document its features, I need to set it up and test them.