Announcing April’s Guest Post Series

Since January 2018, I have been blogging thrice a week about pursuing a Masters in Technical Communication, being a Technical Writer, and becoming “more technical”. However, all the posts were based solely on my experience, thereby providing only my limited perspective about the field of technical communication. I wanted to know more about others’ experiences and provide diverse perspectives on the blog. So I invited the technical communicators that I have admired and learned from over the years, to share their experiences on this blog, and they accepted my invitation!

Hence in April, I am tuning down the frequency of my posts from thrice a week to once a week to focus the spotlight on our guest bloggers each week. Here’s the schedule:

April 4: Bart Leahy – Former technical writer at NASA and Disney, currently freelancing. In his post, Bart gives us a sneak peek into the day-in-the-life of a freelancer juggling multiple projects.

April 11: Jason Tham – A student pursuing a Ph.D. in Technical Communication. In his post, Jason gives us an insight into the collaborative projects in technical communication across academia, service, research, and publishing.

April 18: Swapnil Ogale A technical writer in Australia, Swapnil shares a day in his life as a contract technical writer in Australia.

April 25: Larry Kunz – A veteran technical writer with 30 years of experience, he is a treasurehouse of knowledge!

I am so excited to share their knowledge and insights with you! Stay tuned and don’t forget to subscribe.

List of Open Source Projects with Documentation Opportunities

After last week’s post about Docs FixIt Day at Cockroach Labs, I received several requests asking me to suggest open source projects that people can contribute docs to. As far as I know, almost all open source projects accept docs contributions. The following list includes some open source projects I find interesting:

If you have any favorite docs-friendly open source projects, tell me about them in the comments. And don’t forget to subscribe!

Update 1: Suggestions from the community:

Update 2: Came across this article: Open Source Maintainers Owe You Nothing, which I thought was a mandatory read for anyone who wants to contribute to open source projects. It is important to remember that developers and maintainers of open source projects usually work on these projects on their own time and dime, and it is not their responsibility to help us understand how the project works. We need to put in our own efforts, read all available documentation, learn about the project on our own, before we ask for their help.

Docs FixIt Day at Cockroach Labs

This week, I interrupt your regularly scheduled programming of technical writing techniques to brag about the incredible people I work with, who exemplify a company-wide culture of good documentation.

Let me give you some context: As most of you know, I work as a Senior Technical Writer at Cockroach Labs. For a major product release coming up in April, we had around 163 open issues to be documented for the release. Some of the issues were big-ticket items while a considerable number of issues were small but time-consuming fixes. It wasn’t humanly possible for our team of 4 technical writers to document all the issues before April. While brainstorming possible strategies to complete the documentation tasks, we thought of enlisting the help of our fellow Roachers* to contribute to our docs. The Engineering team had previously organized a successful Bugs FixIt Day, so we decided to replicate their model and announced a Docs FixIt Day.

We planned and prepped for days – announcing the Docs FixIt Day at the weekly team meeting, sorting through the issues and marking the ones we thought the engineers can take up, and of course arranging for snacks. Our fearless leader, Jesse Seldess, brought delicious Babka, and my fellow tech writer, Lauren, baked out-of-the-world, drool-worthy cookies.

We started the day with Jesse’s “Getting Started with Docs” presentation. He discussed the purpose of the FixIt Day, walked the engineers through the Docs toolset (GitHub and Jekyll), and announced the prizes – a Docs-team authored poem** and an Amazon gift card. The prizes would be given to the person who resolved the most Docs issues, and also to the person who resolved the Docs issue with the biggest impact.

We had 24 people in attendance for the kickoff session – in office as well as remotely. At the start of the day, we had 83 open issues marked as FixItDay. The participants included interns, engineers, engineering managers, and our CEO as well! They self-assigned the issues they wanted to work on and wrote docs all through the day till 6 PM. The last I checked on the day, we had 52 open PRs ! And people were contributing PRs even after that, so the final count might have been higher. (IMO, Jesse deserves an award for reviewing all the PRs).

To say the day was a success is an understatement. Not only did we get a big chunk of our documentation done, but the event also fostered cross-functional team collaboration. The engineers’ enthusiasm was infectious – they were totally invested and involved in the whole Docs process. We had given them the option of either working on the Docs end-to-end (as in they write, edit, revise the content), or just provide the raw content and the Docs team takes over the PR for them. But almost all engineers opted to complete the docs themselves, asking us for assistance with our GitHub process and SQL diagram generators and so on. This gave them a chance to understand the Docs toolset and they voluntarily helped us figure out how we can optimize the toolchain.

I have never been prouder to be a part of a company as I am now. As a technical writer, I am intensely aware of how big of an anomaly our company culture is. In most companies, docs are added as an afterthought and technical writers are considered a pesky annoyance. At Cockroach Labs, however, the importance of good, sound documentation is deeply ingrained in our DNA. And that is evident in all forms of documentation we produce – RFCs, user docs, training materials, or even meeting notes.  That is also evident from the fact that we already have a team of 4 technical writers for a team of around 35-40 engineers, when it is not unheard of at other companies to have one technical writer for 120 engineers. It is a privilege to work at a company where people genuinely care about good documentation and are willing to do everything they can to ensure we maintain the quality documentation we have. And I am thankful to be a part of an immensely talented team that is rooted in our core values: “Aim High and Build to Last”.

You can check out the awesome work our team did for Docs FixIt Day here.

*Roachers n. People who work at Cockroach Labs

**Poems written to express our appreciation for our peers is a time-honored tradition at Cockroach Labs.

My Tech 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

 

Technical Communication Journals and Publications

Before I started my graduate program in Technical Communication, I had no idea about the immense wealth of knowledge that are the Tech Comm publications. This post provides information about the Tech Comm journals and publications that helped me in my graduate program as well as thesis. Following are peer-reviewed quarterly journals published in the field of technical communication:

Technical Communication (Published by STC)

Technical Communication Quarterly (Published by ATTW)

IEEE Transactions in Professional Communication (Published by the Professional Communication Society of the Institute of Electrical and Electronics Engineers (IEEE))

Journal of Business and Technical Communication

Journal of Technical Writing and Communication

In the upcoming blog posts, I will review articles from these journals to give you an idea of the type of articles published in the academic tech comm world.

 

GitHub for Beginners

GitHub is a popular version control and collaboration. In my experience, learning GitHub can add tremendous value to your profile as a technical writer. GitHub enables you to contribute to open source projects and build your documentation profile. It also demonstrates your collaboration skills (working with developers and other team members),  knowledge about version control, and overall technological literacy and comfort.

Getting started with GitHub is fairly easy. Follow the official guide to create your own repository!

And watch this video: