Docs (and tech comm) items of interest: docs in two recent “state of” reports; upcoming Write the Docs conferences; the 2022 ATTW conference; Docs for Developers; OSS docs; DevTechDocsOps, are we paying technical writers enough?

The State of Documentation

Two recent high-profile “state of” reports have helped highlight the key role documentation plays in building better software:

The 2021 Accelerate State of DevOps report includes data on documentation practices for the first time in the report’s history (just jump to page 21 for all the documentation goodness). Notably, the report focuses on the internal documentation practices of software teams:

Good documentation is foundational for successfully implementing DevOps capabilities.

For the first time, we measured the quality of internal documentation and practices that contribute to this quality. Teams with high quality documentation are better able to implement technical practices and perform better as a whole.

The Continuous Delivery Foundation (CDF), one of the sponsors of the report, did a lovely blog post to recap the report, and also hosted a follow-up discussion on the report results (in which they kindly invited me to participate).

GitHub’s 2021 State of the Octoverse report also makes documentation one of its main topics, with an entire section on Creating documentation to support developers consisting of the following topics:

• Critical documentation
• Contribution guidelines
• README–or not?
• Issues as documentation
• Good first issues
• Docs for productivity and culture

While the entire docs section is worth a read, the introduction to the “Critical documentation” topic is worth citing in full here (but also check out the charts and data in the report).

Documentation is critical but often under-invested

Documentation is often an under-resourced area of projects, despite being critical to onboarding new contributors, improving the quality of work, and creating shared understanding.

What the data shows: Sharing and sourcing knowledge through different forms of documentation improves productivity both in open source projects and at work. Internal documentation covered onboarding, governance, tutorials, structure/dependencies, and best coding practices.

The 2021 State of the Octoverse report also cites the 2021 Accelerate State of DevOps report in its “Docs for productivity and culture” topic:

Documentation is good for productivity and culture — it’s a win-win

Strong cultures built on trust are supported by good information flow, and recent research by DORA shows that quality documentation improves performance.

I love GitHub’s nod to the Accelerate State of DevOps report here, and also the acknowledgement that many folks still refer to it as “the DORA report” years after Google Cloud acquired DevOps Research and Assessment, LLC in 2018. It is also worth noting that Dr. Nicole Forsgren, one of cofounders of DORA and co-author of the book that gives the Accelerate report its updated name, is currently a partner at Microsoft Research and one of the authors of the 2021 State of the Octoverse report.

Upcoming Write the Docs Conferences

Write the Docs is organizing two upcoming virtual conferences:

Write the Docs Portland 2022 will take place on May 22-24, 2022. As of the publication date of this post, tickets are still available and the full schedule is up on the conference site. As some of you may recall, I had such a great experience at the virtual WtD Portland 2021 conference that I devoted an entire Docs Roundup post to recapping the event.

Write the Docs Prague 2022 will take place on September 11-13, 2022; the CFP has yet to be posted.

2022 ATTW Conference

The Association of Teachers of Technical Writing (ATTW) will hold its annual conference virtually from June 20-30, 2022):

Our 2022 conference will span 10 days and include approximately 34 Taking Action workshops, a keynote speaker, an opening session, and an awards session. Check out the full CFP for topic ideas and our call to action.

The full schedule is not yet available, but this year’s theme is “Taking Action: Reimagining Just Futures in Technical Communication.” Dr. Safiya Noble, author of Algorithms of Oppression: How Search Engines Reinforce Racism (2018), will be keynoting.

@jsanofranchini, @kristen4moore, and I are excited to announce the #ATTW22 virtual conference keynote speaker, Dr. @SafiyaNoble!

Save the date for her keynote address:
Wednesday, June 22 at 2PM EDT via Zoom.

Details about conference registration coming soon! Follow @ATTWorg. pic.twitter.com/AVj506uCcq

— Donnie Johnson Sackey 🥴 (@donniejsackey) April 15, 2022

While I have discussed some of the differences between academic and tech industry events, Dr. Noble’s keynote is a potential draw for both audiences. According to the ATTW website, attendees must be current ATTW members, and can then register for the conference (for an additional fee) through the membership portal.

Docs for Developers (2021)

Released last year, Docs for Developers: An Engineer’s Field Guide to Technical Writing articulates its intended audience as follows:

Ideal for software developers who need to create documentation alongside code, or for technical writers, developer advocates, product managers, and other technical roles that create and contribute to documentation for their products and services.

Collaboratively written by experienced tech industry documentarians Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse, the book walks its audience through the processes of creating documentation to accompany the launch of a fictional service named Corg.ly. Or, as Kelsey Hightower states in the book’s forward:

The authors of this book have worked on documenting several difficult technical projects in places like the Linux Foundation, Google, Stripe, LaunchDarkly, and the UK government, working to meet developers’ needs through documentation. In this book, they distill their experience into a step-by-step process that you can apply to any project, along with case studies, tutorials, and tips based on hard-won experience. (xx-xxi)

I found the main content of the book per se to be very useful and easy to navigate, and I appreciate that it goes beyond the documentation required for an initial product/project release to discuss “Maintaining and deprecating documentation” in the last chapter. There is also an excellent appendix on “When to hire an expert” (as in “when to hire a documentation specialist”) that I plan to cite. A lot.

Docs for Developers is especially timely in light of a growing industry trend to encourage developers to (pun intended) develop stronger writing and communication skills. This is evident in materials that software vendors produce for their own developers, such as Google’s tech writing courses for engineers, which I have written about previously. Companies like DataDog have reportedly hired engineers to write technical content full time. Writing and communication often come into play for roles that are not documentation or content-centered. As Gergely Orosz (author of this post on Becoming a Better Writer as a Software Engineer) points out, companies like Amazon consider writing skills when hiring for some engineering roles.

OSS docs: best practices & common tasks

As I noted in my writeup on the Write the Docs Portland 2021 Conference, I first learned about The Good Docs Project from Abigail McCarthy’s talk on A guide to getting started in open source. The stated purpose of the Good Docs Project:

The goal of the Good Docs Project is to improve open source software documentation by providing high quality templates and writing instructions to the open source community and beyond.

I was therefore delighted to see this recent post from VMware (where Abigail works as a Staff Open Source Technical Communications Manager) on Building Better Documentation Practices for Developers, Part 1 that covers The Good Docs Project and topics such as docs advocacy:

There’s a term that’s been kicking around in the open source space known as “docs advocacy.” Defined by Erin McKean, Open Source Program Manager for the Season of Docs at Google, “it’s a developer-focused practice that encourages better software documentationーwhether through creating good docs yourself, helping others produce docs, or by creating a culture that enables good docs to be produced.”

The post goes on to interview Alyssa Rock, a Staff Technical Writer at VMware (she also serves on The Good Docs Project’s steering committee), and explains how docs-as-code processes can help lead to better documentation practices. Alyssa also has a really good post on capturing some of the many, many tasks that technical writers do when working in OSS.

DevTechDocsOps

Recently the tech industry has seen not only the smooshing of categories, technologies, and processes, but also the smooshing of terms. The success of DevOps alone has inspired terms such as DevSecOps, GitOps, CloudOps, AIOps, and DocOps.

While I love a good neologism, my far and above favorite of the bunch is “DevTechDocsOps” as coined by LaunchDarkly’s Heidi Waterhouse (one of the Docs for Developers co-authors) in her lightning talk from the 2021 DevOps Loop conference. This talk is very much worth your time (and mentions the 2021 DORA report):

As Heidi notes in the talk, she gave a much longer (workshop) version at the 2021 StrangeLoop conference (and I really wish a recording of the longer talk was available).

Are we paying tech writers enough?

TL;DR: no, we are not.

Last summer I wrote about the value of documentation, the wealth of open positions related to tech writing and documentation, and what companies looking to hire for these positions can learn from the (then) most recent Write the Docs Salary survey. Among my takeaways: value tech writers, pay them well, and hire more of them.

MongoDB’s Matt Asay took my arguments one step further, asking Should documentation writers get paid more than developers? and soliciting a thread of great replies in the process.

While I don’t know that we will see tech writer compensation significantly outpace developer salaries any time soon, I very much believe that documentarians deserve recognition and compensation that is on par with developers.  Or, as Pulumi’s Kat Cosgrove puts it:

Tech writers should be leveled and paid the same as engineers imo

— Kat 2fragz Cosgrove (@Dixie3Flatline) February 10, 2022

Miscellany

• Google’s 2022 Season of Docs is already underway; while the organization application deadline has passed for this year, there are a few more weeks left until the technical writer hiring deadline (May 16)
• Check out AWS’s Emily Freeman’s twitter query: where’s the best place to publish developer content these days?
• More love for the Good Docs project
• Let’s Talk Docs: a podcast on documentation and sustainable OSS hosted by Portia Burton and Eric Holscher
• More from Portia Burton: Nerds Don’t Respond To Marketing; Try Technical Documentation Instead
• Cloudflare recently moved its docs to Hugo (and according to the docs README, deploys them using Cloudflare Pages).
• Kim Maida on developer experience and best in class docs
• A thread on API docs from Pratim Bhosale
• My RedMonk colleague Kate Holterhoff on Continuous Documentation
• A Twitter thread countering the argument that “we move too fast to document” (a great topic with amazing replies)
• ICYMI: Devs For Ukraine, “a free, online engineering conference with the goal to raise funds and provide support to Ukraine,” is happening next week (April 25-26).

Worth 1000 words

From the excellent Cassidy Williams (sound on for some Reading Rainbow nostalgia):

Turns out reading the docs is better than just logging every other line 💫 pic.twitter.com/PQPWPeWGba

— Cassidy (@cassidoo) March 14, 2022

 

Have a recent/upcoming docs item you want me to know about? Drop me a line or find me on Twitter.

Disclosure: Cloudflare, the Continuous Delivery Foundation (CDF), GitHub, Google Cloud, LaunchDarkly, Microsoft, MongoDB, Pulumi, and VMware are RedMonk clients.

Image information: miniature of Hildegard of Bingen (artist unknown) from Wikimedia Commons; image is in the public domain. Per the Medieval Tech Comm section of Docs Roundup 1.2:

Although Hildegard is more widely known for her contributions to music and theology, she is also considered a medieval technical communicator.

Also, she was clearly using tablets way before they were “a thing.”