Write the Docs Portland 2021 has concluded, and I wanted to share a couple of key insights and my observations from the conference.
First, it was fun, a wonderfully nice group of people, and well organized. 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 at Write the Docs this year, but there were so many more! All of the talks will be posted to the Write the Docs YouTube channel in a week or so.
