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 firstname.lastname@example.org. And don’t forget to subscribe!
Bonus: I track the various phases of each document in my bullet journal: