I was happy to attend the Write the Docs Portland virtual conference this year. I physically attended a couple of years ago and wanted to see what this virtual experience was all about. It. Was. Great.

The Venue

The virtual platform used for the conference was called Hopin. For the Monday evening social event, they used SpatialChat, which was pretty unique. Hopin also worked great. Presentations on the main stage were broadcast in one channel, where participants could ask questions in chat. Some presenters pre-recorded their talks and answered the questions in chat as they came in. The unconference sessions were held in seven separate channels, with up to 20 people sharing audio and video per channel, and any number of people in chat. That left plenty of openings for folks to gather and talk about common interests.

Writing Day

Not straying from tradition, the pre-conference Sunday was dedicated to Writing Day. This was the first Writing Day I actively participated in, and it was an interesting learning experience. Each table I visited did things slightly differently.

The Good Docs table

The Good Docs project is an attempt to provide documentation and templates to help folks provide documentation artifacts for their open source projects. This table was mostly a presentation of the project followed by a brainstorming workshop where folks could contribute ideas for templates to provide as artifacts.

The Write the Docs style table

I stopped in to say “Hi” to a veteran IBM contractor and long-time STC volunteer, Barrie Byron, as she led a table to improve and add resources to the Write the Docs style page. They needed resources for a new accessibility page and I was happy to provide the IBM equal access toolkit as an added link to the page. Folks contributed content to the documentation Github repo by submitting their ideas in issues and chat, while Barrie and a crack Github user implemented all the changes.

The GitLab table

GitLab is very good about encouraging and helping folks participate in open source. Two folks from GitLab came prepared with many copyediting issues for us to tackle. They use Vale as their documentation test suite (like Acrolinx but lighter weight), and I was given an issue where Vale flagged instances of future tense to correct to present tense. The content was captured in the GitLab documentation by all of us participants editing the markdown files and submitting merge requests (MRs, same as Github PRs).

Conference Days

Same as in 2019, I chose to take part in as many unconference sessions as possible, since the formal track was being recorded and I can listen later. I did listen to the lightnight talks, though, which were 5 minutes each, very concise and to the point. The kind of presentations I like.

Main stage and lightning talks

You can find the main presentations and lightning talks on the Write the Docs YouTube Portland 2021 playlist. Most of the earlier conference talks are very good and worth watching, too. Browse around the playlists from previous years and something’s sure to spark your interest.

Social Event

On the first night there was a social event during happy hour (5-7 p.m.). Only about 40 people showed up, but this was a unique experience. The platform we used was called SpatialChat. Like any video conference, your headshot is displayed with all the others on the screen. However, you’re a little circle in a room, and you can drag your circle between groups. The closer you move to another person’s circle the louder they become, hearing only the folks in your area. It’s probably the best you can get to a virtual party without VR. Looking at the web site, you might even be able to try it free for small gatherings.

Unconference

There were a total of 31 unconference sessions of 64 possible slots, each lasting about 40 minutes. The morning of the first day offered only a few sessions. Seems folks had to warm up a bit before choosing to hold a session.

I wish I could have attended them all, but it wasn’t possible. The slots were divided such that there could be a max of 6 sessions held at the same time. And on the second day, nearly all the slots were filled. Here are some notes from the sessions I was able to attend:

How to review docs changes well, hosted by Kailie Yuan, MongoDB

Not surprising, most folks in the session used Github and reviewed docs with issues, discussions, and pull requests. No one mentioned the need for a review server like we’re accustomed to at IBM. I was surprised to learn that even Sales folks and Product Managers would participate in Github pull request reviews in addition to the core Development SMEs.

How to get Localization Right, hosted by Markus Seebauer, Gateway Translations

Markus presented how his company uses Crowdin to provide continuous integration pipelines for translation into client content. I checked out the Crowdin web site and it looks well put together, supporting a wide variety of file formats, with APIs, tools, integrations with many repos and CMSes, and machine translation such as IBM Watson Language Translator. Their main translation resource looks to be crowd-sourced human translators. It seems pretty slick. I might try it on my personal web site content or theme to see how it goes.

Transitioning from developer to technical writer, hosted by Kailie Yuan, MongoDB

A few developers got together to discuss the challeges of getting more involved in documentation. I and another writer were there to provide moral support. It was a fun discussion. We even chatted about skills and talents that differentiate a coding brain from a writing brain and also those that are shared.

Creative Template Use, hosted by Kenzie Woodbridge, British Columbia Institute of Technology

A follow-up discussion from The Good Docs Project, we chatted about various details in providing templates. I’m not gonna lie, we got kind of in the weeds and I unfortunately don’t remember much and didn’t take notes.

How to get professional quality PDFs using the Asciidcotor toolchain, hosted by Elisa Sawyer RISC-V

Asciidoctor creates great looking PDFs with it’s basic style already, so I was just interested in seeing what Elisa did. And, yep, the RISC-V style looks great, and it’s open source should anyone want to use it and customize it to their own.

Sphinx: State of the Union, hosted by Juan Luis, developer advocate at Read the Docs

General discussion about the Sphinx documentation system: current struggles, reStructuredText vs MyST (Markdown), feature requests, outstanding bugs, missing documentation, integration with Jupyter notebooks, comparison with other systems. I had used Sphinx once to produce API documentation from source code and comment introspection, but that’s about it. So, I learned lots about the other things that Sphinx can do. Many were interested in the nice looking Sphinx theme used for Scylla, which Laura Novich of Scylla was happy to showcase.

DocOps Happy Hour! Hosted by Jodie Putrino, NGINX/F5

We brought our beverage of choice and talked about DocOps. One question came up about what DocOps is: “Is it just about tooling?” It’s thrown around as part of Write the Docs parlance quite a bit, along with docs as code, so yeah, it’s usually talked about in the tools context. But Jodie says no, it’s not just about tools. It includes a whole range of processes, and I agree. It’s the day-to-day operations involved in creating doc, from design, to information architecture, to style and quality, to metric analysis, and yes to tools, building, and publishing.

Wrap up

That DocOps happy hour was a great way to close out the conference on Tuesday. Overall, although the Portland conference is the largest of the Write the Docs conferences, I don’t see why anyone would limit themselves to just this one, at least when a virtual experience is required. The other Write the Docs conferences in other parts of the US, EMEA, and AP are growing. It would be interesting to attend them as well. In-person experiences are more exciting and meaningful, for sure, but this virtual experience was pretty darn good itself. I’ll be sure to attend again either way.

Cheers!