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.

Article Review: Academics Are from Mars, Practitioners are from Venus: Analyzing Content Alignment within Technical Communication Forums

Note: I had written the following article review as part of my Annotated Bibliography project during my graduate program.

Boettger, R. K., & Friess, E. (2016). Academics Are from Mars, Practitioners Are from Venus:Analyzing Content Alignment within Technical Communication Forums. Technical Communication63(4), 314-327.

Boettger and Friess’ article investigates the content misalignment in the technical communication publications for academics and practitioners. In this empirical study, the authors conducted a quantitative content analysis of 1048 articles published in four leading technical communication journals and one published magazine over a period of 20 years. The study confirmed the disconnect between the academic and practicing communities and helped the authors formulate recommendations to bridge the disconnect.

The authors sought to understand how is content broadly classified across the publications, what primary content areas do the publications address, and who are the primary audiences for the publications. The authors selected the four leading publications (JBTC, TC, TCQ, and TPC) based on previous studies which found these publications to be the leading publications in technical communication. They selected Intercom as the longest published magazine in technical communication. Because Intercom has been published as a magazine since 1996, the authors selected January 1996 as the starting time for the time period of analysis. They analyzed the articles from 1996 to 2015, when this study was published. The authors populated the 3605 articles published in all five publications in the 20-year timeframe in an Excel sheet and used a random number generator software to randomly select 30% of the total articles.

The authors coded the 1048 articles for four content variables: forum, broad topic, primary topic, and primary audience. Over six norming sessions, three raters used an independent sample of articles to test and refine the coding categories. Then over 10 coding sessions, three raters coded the sample set of 1048 articles. Inter-rater reliability was calculated with Krippendorff’s alpha coefficient. The results of the agreement were: forum (100%), broad topic (80.2%), primary topic (82%), and primary audience (76%).

The authors analyzed the data through descriptive statistics and correspondence analysis (CA). CA is a geometric technique used to analyze two-way and multi-way tables containing some measure of correspondence between the rows and columns. CA reveals patterns in complex data and provides output that can help researchers interpret these patterns.

Based on the analysis, the following results were obtained: Intercom published more process-oriented articles, whereas the journals published more education-oriented articles. There was a strong association between the following forum and broad topic: Intercom and profession, TCQ and education, and TC and product. As for primary content, professionalization and technology content areas were prominent in Intercom, whereas content on pedagogy, rhetoric, assessment, comprehension, and design were prominent in the journals. Rhetoric as a topic was identified only in journals. A strong association was found between the following forum and primary topic: Again, Intercom with professionalization, TCQ with rhetoric, and TPC with pedagogy. With respect to the primary audience, the primary audience for the journals were academics and managers, while for Intercom, the primary audience was writers, content developers, managers, and so on. There was a strong association between the following forum and primary audience: Intercom and writer/content developer, JBTC and TCQ with academic, and TC and manager.

Based on the results, the authors verified the disconnect between the publications and recommended remedies to bridge the disconnect. They recommend unifying the existing forums, identifying new audiences, and involving practitioners in technical communication research.

The main question about the study is the premise that the content forums for technical communicators need to be unified. As we learned in the History of Technical Communication course, the different publications were started to serve different audiences and meet their varied requirements. Unifying the forums would defy the original purpose of the publications. Another concern is the publications excluded from the study. Not all academics and especially practitioners read the publications studied in this article. In today’s Internet age, popular online blogs such as I’d rather be writing and ffeathers need to be considered to ensure maximum readership is accounted for.

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

 

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:

 

 

Deep Work for Tech Writers

One of the life-changing books I have read in my professional life is Deep Work (affiliate link) by Dr. Cal Newport. As I discussed in the Day-In-The-Life blog post, I start my day with one-hour (2 Pomodoros) of Deep Work. And that has been the secret to my productivity and success as a technical writer.

Following are a couple of resources that summarize the book far better than I could have. Go through the resources, try out the technique, and drop me a line at hello@amrutaranade.com to let me know what you think of it. And don’t forget to subscribe!

Book summary: https://fourminutebooks.com/deep-work-summary/

YouTube video:

 

Technical Communication Conferences and Communities

One of the benefits of being a part of the academic as well as practicing circles of Technical Communication is that I can participate in conferences and communities in both domains. This post lists the conferences and communities that I find useful:

For Practitioners

Online Communities

Conferences

  • STC India
  • WriteTheDocs Portland
  • STC meetups in the Bay Area
  • tcworld

For Academicians

Online Communities

  • WomenInTC Slack and Twitter
  • ATTW mailing list
  • CPTSC mailing list

Conferences

  • ATTW conference
  • CPTSC conference
  • GPACW conference
  • STC regional conferences (I attended two: one in Springfield and another in Missouri State University)

Update: Came across this incredible list of conferences. Check it out!

Containers for beginners

Last week, we learned about cloud platforms. This week, let’s discuss the next step in the technological evolution: Containers.

Two of the popular containers are Docker and Kubernetes (an incredible open-source project):

 

Pomodoro for Tech Writers

Thе Pоmоdоrо Tесhniԛuе iѕ a time mаnаgеmеnt mеthоd developed bу Frаnсеѕсо Cirillо in thе late 1980s.Thе tесhniԛuе uѕеѕ a timеr to break dоwn wоrk into 25-minute intеrvаlѕ, ѕераrаtеd bу 5-minute breaks. These intеrvаlѕ are nаmеd Pоmоdоrоѕ, thе plural in Engliѕh оf the Itаliаn word Pomodoro (tоmаtо), after the tоmаtо-ѕhареd kitchen timеr thаt Cirillо uѕеd аѕ a university ѕtudеnt.

The Pomodoro tесhniԛuе helps you асhiеvе the following:

  • Imрrоvе efficiency
  • Kеер away from diѕtrасtiоns and fосuѕ оn thе task аt hand
  • Imрrоvе timе-ѕеnѕе
  • Eliminаtе ѕtrеѕѕ burnоutѕ
  • Assist in аnаlуzing timе taken fоr tаѕkѕ

Hоw thе Pоmоdоrо Tесhniԛuе wоrkѕ

Thе Pоmоdоrо Technique rеgulаtеѕ when to diligеntlу fосuѕ оn a tаѕk аnd whеn you ѕhоuld take a brеаthеr.

This tесhniԛuе iѕ centered аrоund brеаking your timе down into роmоdоri (one Pomodoro iѕ еԛuаl tо 25 minutеѕ). You lоg a ѕресifiс tаѕk уоu are going tо work on and thеn ѕрrint уоur wау thrоugh thаt роmоdоrо. Aftеr 25 minutes of dеdiсаtеd wоrk, the timеr gоеѕ off аnd уоu tаkе a nice 5-minute brеаk frоm your wоrk.

Once your brеаk is over, уоu ѕtаrt аnоthеr 25 minutе long Pomodoro. This new роmоdоrо саn be dedicated tо thе ѕаmе tаѕk аѕ bеfоrе (if уоu did not complete it during thе previous роmоdоrо) оr a new оnе. Aftеr every 4 роmоdоri (рlurаl fоr роmоdоrо), уоu саn tаkе a lоngеr break, if уоu would like (ѕuсh аѕ fоr 15 minutеѕ).

While уоu’rе wоrking уоur way thrоugh a роmоdоrо, уоu can temporally interrupt it for uр to 45 seconds, if need bе. If thе interruption lаѕt fоr longer thаn thаt, уоur dеdiсаtеd fосuѕ оn thе mаin tаѕk iѕ viewed to bе lоѕt, аnd thuѕ thе Pomodoro iѕ rеѕеt (having tо ѕtаrt over at 25 minutеѕ) again.

Thе dеfаultѕ of 25 minutеѕ реr роmоdоrо, 5 minutеѕ реr rеgulаr breaks, 15 minutеѕ реr lоngеr break, and 45 ѕесоndѕ реr intеrruрtiоn seem to wоrk wеll for me аnd most people I knоw whо’vе triеd thiѕ hаndу tесhniԛuе оut. Hоwеvеr, that said, thоѕе arbitrary аllоtmеntѕ оf timе саn bе сhаngеd dереnding оn уоu реrѕоnаl hаbitѕ and ѕсhеdulе, ѕо аѕ lоng as уоu consistently ѕtiсk with thе аllоtmеntѕ thаt уоu’vе lаid оut. Fоr example, ѕоmе реорlе may prefer to wоrk “in the zоnе” for 50 minutеѕ, аnd then tаkе a 10 minutе break.

Why the Pomodoro Technique works

It is common experience that we can focus on a given task only for a short period of time before we get distracted (or seek out distractions). The Pomodoro technique helps to quantify and manage those focus periods. If you know you have to work for just 25-minutes, and then you can surf the web or check Facebook guilt-free, you will be more inclined to put in those 25 minutes of focused work. And you can get a lot done with 25 minutes of focus!

This technique has been a game-changer for me in terms of my productivity. As I discussed in the Day-In-The-Life blog post, I start my workday with at least 2 Pomodoros of focused work (which is almost one hour), and then I am free for the rest of the day to attend meetings, do some mundane tasks, socialize, or just goof off, because I have done the most important tasks for the day already.

The Pоmоdоrо Tесhniԛuе fоrсеѕ me to think in tеrmѕ of асtiоnѕ that nееdѕ tо bе tаkеn in order tо еffесtivеlу gеt things dоnе. It also imроѕеѕ thаt I рriоritizе аnd dесidе whiсh асtiоn I’m gоing to work оn. By hеlрing tо limit my аttеntiоn ѕраn tо a ѕinglе activity, thiѕ tесhniԛuе аidеѕ me in ѕtауing focused (instead of hopping between a handful оf diffеrеnt tаѕkѕ аnd/оr diѕtrасtiоnѕ).

Rеviѕiting my dаilу Pomodoro lоgѕ highlights whеrе I spend my timе аnd hоw рrоduсtivе I was thrоughоut a given timе period.

I now think of my tasks in terms of thе number оf роmоdоri thаt a givеn tаѕk might rеԛuirе. I diѕсоvеred that еvеn сhаllеnging tаѕkѕ саn оftеn bе tаkеn care оf in a handful of pomodori ѕеѕѕiоnѕ.

Try out the technique and let me know if it works for you. Drop me an email at hello@amrutaranade.com. And don’t forget to subscribe!

P.S: Here’s my favorite Pomodoro playlist: