Recent docs (and tech comm) items of interest: The Inclusive Naming Initiative, ACM-SIGDOC 2021 Conference; Write the Docs Portland 2021 Conference, the latest Season of Docs, Open Web Docs, Spotify’s TechDocs, Your Computer is on Fire (2021)

Hildegard of Bingen: medieval tech writer

 

Inclusive Naming Initiative

In November 2020 the Cloud Native Computing Foundation (CNCF) announced the creation of the Inclusive Naming Initiative. Per the Initiative’s “About” page:

The Inclusive Naming Initiative’s mission is to help companies and projects remove all harmful and unclear language of any kind and replace it with an agreed-upon set of neutral terms. The initiative’s goal is to define processes and tools to remove harmful language from projects. This includes creating a comprehensive list of terms with replacements, language evaluation frameworks and templates, and infrastructure to aid the transition.

Leadership includes folks from the CNCF, Cisco, IBM, Red Hat, and VMware.

While the Initiative is still relatively new, resources already include the beginnings of a word replacement list and a framework for evaluating harmful language.

To get involved: meetings are held every other week on Mondays at 9:15am PT/12:15pm ET. Meeting invitations can be accessed via the Initiative’s mailing list.

ACM-SIGDOC 2021 Conference CFP

The Association for Computing Machinery (ACM) Special Interest Group on Design of Communication (SIGDOC) is hosting its 2021 conference on the theme Advocacy, Accountability, and Coalitions Across Contexts. The event is planned as a hybrid virtual/in-person event:

October 12 – 14, 2021 Hybrid Conference: Virtual Presentations with In-Person Meetup Hubs across 8 locations worldwide.

Note: Conference presentations, including the Student Research Competition (SRC), will be virtual from October 12 – 14.

Optional In-person Meetup Hubs are based at 8 partner locations worldwide on October 14 in that location’s local time zone.

The full call for papers (CFP) is available on the conference website; proposals are due March 5, 2021 the proposal deadline has been extended to March 12, 2021.

Write the Docs Portland 2021 Conference

The schedule and speakers list are up for Write the Docs Portland 2021 Conference, to be held online April 25-27.

While the entire speaker and talk lineup looks great, I am particularly delighted to see a talk from my former tech writing colleague Abigail McCarthy (currently at VMware) on the schedule. Her talk title and abstract:

A guide to getting started in open source

Open source projects are a great opportunity to grow your skills or learn new ones. Project maintainers are always looking for new folks to help out with various aspects of the project, especially when it comes to documentation. But how do you get started?

For me, this was the most overwhelming question when I first started in open source a few years ago. Coming from a background in closed source, stepping into the open source world felt a lot like stepping into Wonderland to me. There were so many new terms to learn, new ways of doing things, and, the scariest of all, I now had to do everything in front of the whole world. EEEK!

Looking back over my journey starting out as a nervous newbie and transitioning to technical documentation lead for prominent open source projects (Harbor and Velero), I’ll share some lessons learned and tips on how you can get started on your adventure in the world of open source, including

• Researching your path and picking an open source project that fits you
• Gearing up for the trip by getting familiar with commonly used tools and terms
• Plotting your course and knowing what you want out of the experience
• Being ready to ask for help when you need directions
• Remembering you don’t need to get there in a day, start by setting small goals

In addition to talks and lightning talks on the conference track, events include a writing day, an unconference, and a job fair (and if you are looking for tech writing talent, all conference sponsorship options get you a table at the job fair).

Google kicks off another Season of Docs

Google has announced the 2021 Season of Docs:

Season of Docs provides support for open source projects to improve their documentation and gives professional technical writers an opportunity to gain experience in open source. Together we raise awareness of open source, of docs, and of technical writing.

Per the “How it Works” section of the Season of Docs Introduction page:

Season of Docs 2021 will operate as a grant program. Accepted organizations will receive between US$5,000 and US$15,000 to use for a documentation project.

• Open source organizations submit project proposals. Organizations should review the organization proposal guide before creating their proposal. Project proposals include a proposed budget, timeline, and metrics.
• Accepted organizations hire technical writers directly. The Season of Docs grants will be disbursed in two payments; 40% upon hiring a technical writer, and 60% after receiving the final evaluation and case study. For more information on receiving grants, please visit our grants for organizations guide.
• Interested technical writers can signal their willingness to participate by contacting organizations through their project pages and by adding themselves to the Season of Docs technical writer directory. We encourage interested technical writers to work with organizations to create project proposals.
• Organizations submit their final project reports and case studies by the program deadline. Final project reports and case studies outline what the organization and technical writer learned during the project.
• At the end of the program, the Google program administrators publish the project reports and case studies. Google program administrators will also follow up with the organizations at intervals to ask followup questions about the project metrics.

This year’s timeline page contains deadline information; notably the organizational application deadline is March 26, 2021.

Information on previous participants and projects is available for 2019 and 2020.

Open Web Docs

The Open Collective announced the creation of Open Web Docs. Per the Open Web Docs landing page:

Open Web Docs is a collective of people and organizations who believe well-maintained web documentation is critical digital infrastructure that delivers immense social and economic benefits. We provide full-time support to key documentation platforms such as MDN Web Docs, and empower communities to participate equitably with companies to create and maintain important content that is accessible and inclusive.

Our 2021 priority is building a cooperative, public documentation roadmap for MDN, bolstering core web documentation and browser compatibility information while supporting the platform’s migration to GitHub and fostering a healthy contributor community.

As noted in the related announcement blog post, numerous sponsors and supporting organizations are involved:

Open Web Docs staff are supported by founding sponsors Coil, Google and Microsoft, with additional financial support from Igalia and generous backers on Open Source Collective. Mozilla, Samsung, and W3C provide additional support and participation. Participating orgs are collaborating on content work via weekly editorial and OWD steering committee meetings, and there are plans to create a shared process as we get deeper into the work.

TechDocs: Docs as Code at Spotify

In March 2020, Spotify open sourced Backstage, a platform for creating developer portals. Backstage was accepted as a CNCF Sandbox project in September 2020, and in the same month Spotify also open sourced a version of Tech Docs, a docs-like-code Backstage plugin based on the system Spotify uses internally. As Spotify Product Manager Gary Neimen writes in the announcement blog post:

We are quite sure the main reason for the success of TechDocs is our docs-like-code approach — engineers write their technical documentation in Markdown files that live together with the code. During CI, a documentation site is created using MkDocs, and all sites are rendered centrally in a Backstage plugin. On top of the static documentation, we incorporate additional metadata about the documentation site — such as owner, open GitHub Issues, Slack support channel, and Stack Overflow Enterprise tags.

You can check out the TechDocs product documentation here, or a more recent post from Neimen on Ten tips for maintaining a long-term relationship with docs like code (the opening of which credits Riona MacNamara’s Write the Docs 2015 talk as an inspiration).

Anne Gentle (author of the 2017 book Docs Like Code) was kind enough to surface Neiman’s post. I also recommend checking out Gentle’s own post on Survey results for learning and teaching docs-like-code techniques

Docs as team effort

In November Amanda Casari cited a Tensorflow blog post on How TensorFlow docs uses Jupyter notebooks. As Casari points out, the post considers documentation to be a “team effort”.

I love how Tensorflow talks about documentation as a team effort, as well as how selecting their documentation tool as a community tool allows for greater participation and engagement w/ community members.

cc/ @rionam + @emckean (my "it's not done until it's documented" heroes)

— Madame Treasurer commandasaurus 🦖 (@amcasari) November 12, 2020

From the post itself (in the section on “Better Collaboration”):

Software documentation is a team effort, and notebooks are an expressive, education-focused format that allows engineers and writers to build up an interactive demonstration. Jupyter notebooks are JSON-formatted files that contain text cells and code cells, typically executed in sequential order from top-to-bottom. They are an excellent way to communicate programming ideas, and, with some discipline, a way to share reproducible results.

Books about tech

Out on March 9, 2021: Your Computer Is on Fire, a collection of essays edited by Thomas S. Mullaney, Benjamin Peters, Mar Hicks, and Kavita Philip. Publisher’s summary:

Techno-utopianism is dead: Now is the time to pay attention to the inequality, marginalization, and biases woven into our technological systems.

This book sounds an alarm: after decades of being lulled into complacency by narratives of technological utopianism and neutrality, people are waking up to the large-scale consequences of Silicon Valley–led technophilia. This book trains a spotlight on the inequality, marginalization, and biases in our technological systems, showing how they are not just minor bugs to be patched, but part and parcel of ideas that assume technology can fix—and control—society.

The essays in Your Computer Is on Fire interrogate how our human and computational infrastructures overlap, showing why technologies that centralize power tend to weaken democracy. These practices are often kept out of sight until it is too late to question the costs of how they shape society. From energy-hungry server farms to racist and sexist algorithms, the digital is always IRL, with everything that happens algorithmically or online influencing our offline lives as well. Each essay proposes paths for action to understand and solve technological problems that are often ignored or misunderstood.

Contributors include all four of the volume’s editors (with Mar Hicks sharing one of my favorite author copy unboxing tweets) as well as Janet Abbate, Ben Allen, Paul N. Edwards, Nathan Ensmenger, Halcyon M. Lawrence, Safiya Umoja Noble, Sarah T. Roberts, Sreela Sarkar, Corinna Schlombs, Andrea Stanton, Mitali Thakor, Noah Wardrip-Fruin.

Notably, Halcyon Lawrence–my former Georgia Tech colleague–is one of the program co-chairs for the SIGDOC 2021 Conference mentioned earlier in this post. And if you have not yet read Safiya Umoja Noble’s book Algorithms of Oppression: How Search Engines Reinforce Racism (2018), I highly suggest you add it to your “to be read” list.

Miscellany

• A guide on best practices for accessibility for virtual events from Teresa Terasaki and Juliana Good; thank you to Julia Ferraioli for surfacing.
• A free course on Test Automation for Accessibility by Marie Drake; thank you to Angie Jones for surfacing.
• An excellent thread started by Alejandra Quetzalli generating takes on different documentation sites.
• A thread of docs writing resources originating from PJMetz asking for “resources to help make me a great doc writer.”
• ICYMI, a 2018 ACM Queue article on Why SRE Documents Matter; thank you to Transposit’s Taylor Barnett for surfacing.
• An award winning blog post from Monica Powell on How To Create A GitHub Profile README
• A useful video on how to make videos from Gwyneth Peña-Siguenza; thank you to Stephanie Morillo for surfacing.
• An OH from Bryan Cantrill (with resultant Twitter thread): “A documentation-first culture is an automation-first culture.”
• Reminder to hire more technical writers and to pay them well (advice that we have given to many a RedMonk client).

Worth 1000 words

Developers visiting their blogs like pic.twitter.com/ePshrFDRw4

— Andrew Schmelyun (@aschmelyun) February 21, 2021

 

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), GitHub, Google Cloud, IBM, Microsoft, Red Hat, Transposit, and VMware are all RedMonk clients.

Image information: miniature of Hildegard of Bingen (author unknown) from Wikimedia Commons; image is in the public domain. As noted in Docs Roundup 1.2, Hildegard is often considered a medieval tech or science writer. Also, she was clearly using tablets way before they were “a thing”.