Write the Docs Portland 2021 has concluded, and I wanted to share a couple of key insights and observations from the conference.

First, it was fun, a wonderfully nice group of people, and a well-organized event. Virtual conferences are new for many events and Write the Docs pulled it off really well.

Docs as Code

One repeated theme throughout the conference was technical writers embracing git-based workflows. Writers can more easily collaborate with developers when they work on documentation iteratively. Benefits include avoiding a rush to document at the last minute before a release, less out-of-band communication to understand upcoming changes, and less tooling across an organization.

The cost is that technical writers must learn git, git-based workflows, and plain-text formats, but the benefits are significant, and many writers are learning or already actively using these tools.

Write the Docs has a page with more information on Docs as Code.

Evolutionary Documentation

One of the more striking talks at the conference was “Always complete, never finished” given by Daniele Procida. The talk summary states it best:

an incremental, evolutionary way of working on large documentation tasks that makes every step, from the very first one, a value-adding improvement

Large documentation refactors taken as a single task can be stressful, time-consuming, and may be out-of-date before they are complete. Instead, documentation can evolve in iterative steps that each improve the overall quality of the documentation.

Notice the iterative nature of this process and how it relates to Docs as Code. Yes, they are synergistic and work together nicely.

Vale: A syntax-aware linter for prose

As documentation matures, consistent style and tone grow in importance, and many organizations adopt a style guide or develop their own. While these rules are needed, it can be bothersome and inefficient to need to refer to the style guide manually to keep writing consistent.

One unconference session was devoted to Vale, a tool that lints prose based on the rules in a style guide. I love a good code linter, and this tool looks fantastic for prose.

The Vale ecosystem seems great and includes:

It can be used on a variety of plain text formats, comments in code in many languages, and some GUI-based tools (with a paid subscription). See the complete list of supported formats.

So Many More

These were just a few of the great things from Write the Docs this year, but there were so many more! All of the talks should now be posted to the Write the Docs YouTube channel.

Brian is part of the Developer Success team at Fission and spends a lot of time improving our guide and making better code examples and other ways to help developers succeed in using Fission.