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.

Article Review: Content Strategy: An Integrative Literature Review

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

Clark, D. (2016). Content Strategy: An Integrative Literature Review. IEEE Transactions on Professional Communication59(1), 7-23.

Clark’s article looks at how content strategy is defined and discussed in scholarly and trade literature, and what do the discussions indicate about the direction of the technical communication field. Clark conducted an integrative literature review to find answers to the research questions. Clark traces the emergence of content strategy across multiple disciplines such as technical communication, marketing, knowledge management, and so on. Because content strategy is an integral part of several disciplines, an integrative literature review was the most suitable research instrument.

Clark selected the literature to be reviewed based on whether the work contributed to the knowledge about content strategy, if the work was published after 2009 so as to include recent publications, if the work had the potential of being widely cited and shape the conversation about content strategy, and if the work was publicly available. Based on these criteria, Clark narrowed down the literature to 37 publications comprising of 24 articles and 13 books.

To analyze the literature, Clark resorted to the Classical Rhetorical theory that provides the terminology for discourse analysis. Clark manually read the publications carefully. He noted the definitions and descriptions of content strategy in the publications, and the processes and tools they discussed to meet the content strategy goals. He also collected the employment history of the authors of the publications.

The analysis of the collated data suggests a lack of a common definition of the term “content”. The analysis reveals that content strategy is considered to be the process of creating and maintaining material, is integrated with business and technical needs, and is primarily focused on the customer. The literature promises content strategy as a viable career path for technical communicators, but lacks concrete, real-world examples of putting the concepts into practice. The literature related to content strategy is found in trade publications than academic journals. It indicates that though there is a demand for content strategists in the industry, faculty are not giving it due attention.

The audience for the article are content strategists, instructors of professional communication courses, and documentation managers. Clark discusses the relevant literature snippets thematically instead of presenting a patchwork of quotations and annotations from the literature. He presents a rich level of detail in the literature review. He analyzes the cited literature and provides suggestions for future research in the area of content strategy. He thus meets Hughes and Hayhoe’s (2008, p. 121) criteria of a good literature review.

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.

Article Review: Wearable Writing Enriching Student Peer Review With Point-of-View Video Feedback Using Google Glass.

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

Tham, J. C. K. (2016). Wearable Writing Enriching Student Peer Review With Point-of-View Video Feedback Using Google Glass. Journal of Technical Writing and Communication, 0047281616641923.

Tham’s article discusses a case study of using Google Glass in student peer review sessions. The article also discusses the benefits, challenges, and recommendations of incorporating the process in technical communication courses.

Tham presents an extensive overview of wearable technology and student peer review sessions. He then elaborates on his research methodology of participatory design. In participatory design research, the participants collaborate with the researcher to study the research topic. The study was conducted in three stages. In the first stage, Tham introduced the students to the concept of peer reviews using Google Glass and conducted a device orientation workshop. In the second stage, Tham collaborated with the students to determine the evaluation metrics for the study. In the third phase, Tham and the students used Google Glass to conduct four peer reviews. The first two peer reviews were experimental and the next two reviews were evaluative.

The data collected was triangulated: the data included the students’ narratives, exit survey responses, and Tham’s observations. Using Google Glass, students could track comments and editing suggestions through video recordings. Reviewers may indicate places in writing where revisions are recommended by snapping a picture or recording the suggestions in video. These images and videos could be sent to the respective writers after the review session. With Google Glass, the focus of review shifted from written critiques to spoken comments. Students would employ the think-aloud protocol when reviewing their peers’ drafts.

The students had mixed responses to the exercise. Students appreciated the first-person perspective video feedback helped them understand the reviewer’s thought process while providing feedback. They also found the feedback to be more detailed than written comments. But they found wearing the device physically uncomfortable, reported being distracted by their classmates’ simultaneously talking into their own devices, and felt unsure if they were doing the process right.

On analyzing the students’ responses and his own observations, Tham summarized that the use of Google Glass for student peer review sessions led to personable, unfiltered feedback, provided verbal and visual channels in reviewing, and captured the reviewer’s emotion. Tham also identified the potential challenges to implementing the process as procuring the wearables, connectivity and file sharing issues, technical and financial support, and getting familiar with the technology.

The study is a qualitative developmental study. It has credibility because the students could freely share their opinions, and Tham relied on his observations and not just the students’ self-reports. The study also has transferability because it was conducted in a real-world classroom scenario. Tham shares his course material with the audience, thereby providing material to replicate the study.

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.