Recent docs (and tech comm) items of interest: GitHub open sources its docs; Write the Docs updates; CNCF TechDocs open hours; Google’s tech writing courses for engineers

 

GitHub open sources its docs

Earlier this month GitHub announced that it had open sourced its product documentation at http://github.com/github/docs. In the announcement Janice Niemeir notes:

To make GitHub Docs the best they can be, we know we need to work in the open, with all of you, so that we can stay better in sync with your feedback, ideas, and collective knowledge. The best way to do that is to work in public. That’s why we’re open sourcing GitHub Docs, and opening it up to your feedback and contributions.

The announcement also invites folks to start contributing to the docs:

Everyone using GitHub has a different perspective on what works. We want to make GitHub Docs articles work for all developers who are coming to them from different backgrounds. This is why we’re accepting contributions in many different ways.

GitHub followed up the announcement with a great post from Zeke Sikelianos with further insight on the rationale and process:

This post tells the story of why we wanted to open source the docs, what tools we built and open sourced along the way, and how we worked to make the project welcoming to external contributors.

The post also has a nice section on the care put into the external contributor experience:

We want the process of contributing to GitHub Docs to be as easy for external contributors as it is for GitHub employees, and we’ve built our testing and deployment tools with that in mind. When an external contributor opens a pull request on github/docs, we’ll run the same continuous integration tests and create the same ephemeral staging apps as we do for GitHub employees.

Write the Docs conferences and salary survey

Write the Docs just wrapped the second of three virtual conferences it has scheduled for 2020. While all three events have moved online, each was originally slated to take place in person and is still scheduled according to the time zone of the original conference location.

Write the Docs Prague 2020 kicked off on October 18 with a “Writing Day” followed by two days of conference programming and an unconference. This follows a successful Portland (OR) event that took place in August and precedes the Australia and India event scheduled for December (for which tickets are still available).

The stated goals of these events:

Write the Docs Conferences are focused on documentation systems, tech writing theory, and information delivery. We consider everyone who cares about communication and documentation and their users to be a member of our community. This can be programmers, tech writers, customer support, developer advocates, marketers, and anyone else who wants people to have great experiences with software.

Our conferences create a time and a place for the global community of documentarians to share information, discuss ideas, and work together to improve the art and science of documentation.

The organization is also still soliciting responses to its 2020 Salary Survey (open until November 16, 2020):

Our goal is to help people understand the pay scales and benefits in the software industry around documentation. This will help people get a better understanding of what an appropriate salary is, and then negotiate for a better one.

This is the second year in a row that Write the Docs has conducted such a survey; results from the 2019 survey are available at https://www.writethedocs.org/surveys/salary-survey/2019/

CNCF TechDocs open hours

The Cloud Native Computing Foundation Docs Team will be holding TechDocs open hours at KubeCon + CloudNative Con North America 2020 (the conference runs from November 17-20).

Need help with your project docs? CNCF tech writers can advise you with help for tooling questions, docs triage and workflow, how to attract docs contributors, and maybe review a PR or two.

Open hours are available for KubeCon + CloudNativeCon attendees with a full conference pass. The CNCF Docs Team also holds weekly office hours which are currently posted on its GitHub page.

Google’s tech writing courses (for engineers)

ICYMI, Google has created technical writing courses aimed at engineers:

Every engineer is also a writer.

This collection of courses and learning resources aims to improve your technical documentation. Learn how to plan and author technical documents. You can also learn about the role of technical writers at Google.

The following courses are currently offered:

• Technical Writing One: the critical basics of technical writing
• Technical Writing Two: intermediate topics in technical writing

As the overview page notes, the courses are aimed at software engineers and students, but also “Additionally, many people in engineering-adjacent roles (such as product managers) have also benefited from these courses.”

Each course includes a pre-class reading component designed to work with in-class sessions. While Google offers online in-class sessions, it has also created guides for anyone who would like to facilitate their own in-class sessions using the course materials.

Notably the pre-class materials are useful in their own right. As an example, check out this gem from the Technical Writing One pre-class material on “Audience”:

Curse of knowledge

Experts often suffer from the curse of knowledge, which means that their expert understanding of a topic ruins their explanations to newcomers. As experts, it is easy to forget that novices don’t know what you already know. Novices might not understand explanations that make passing reference to subtle interactions and deep systems that the expert doesn’t stop to explain.

From the novice’s point of view, the curse of knowledge is a “File not found” linker error due to a module not yet compiled.

Google has also curated a short list of technical writing resources at https://developers.google.com/tech-writing/resources

Miscellany

• Earlier this year Technical Communication Quarterly devoted a special issue to “Comics and Graphic Storytelling in Technical Communication”; read the guest editors’ introduction.
• Stephanie Morillo published The Developer’s Guide to Book Publishing (her follow up to The Developer’s Guide to Content Creation); Morillo also has a great thread on tech blog pet peeves
• Thomas Otter’s post on HRTech and inaccessibility (with a nice nod towards the principles of universal design)
• Cloudflare recently rebuilt its Workers docs
• A twitter poll and discussion thread on slide preferences
• A conversation on must-haves for pitch decks
• Three interview posts from my former Georgia Tech colleague Dr. Katie Schaag on her work with teams in Georgia Tech’s Junior Design & CS Tech Comm course sequence:
  • Creative Coding: An Interview with a Computer Science Junior Design Team, Part I
  • Feminist Computational Poetics and Experimental User Interface Design: An Interview with a Computer Science Junior Design Team, Part II
  • Transdisciplinary Collaboration: An Interview with a Computer Science Junior Design Team, Part III

Worth 1000 words (October 2020 mask edition)

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

Disclosure: The CNCF (via the Linux Foundation), Cloudflare, GitHub, and Google are all RedMonk clients.

Image information: Wikimedia Commons; image is in the public domain.