My Writing Process

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:

project workflow

As the image shows, my writing workflow consists of four phases:

Phase One: Research

My research phase consists of the following steps.

  1. 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).
  2. Use the Feynman technique to ensure that you understand the information.
  3. Setup CockroachDB.
  4. 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:

project dashboard

 

15 thoughts on “My Writing Process

  1. Thanks for this informative article, Amruta! I will follow few of your good practices from now on. πŸ™‚

  2. 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!

    1. 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?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s