Write the Docs Portland 2021

The Write the Docs Portland 2021 conference will be held this year on 2021-04-25T16:00:00Z2021-04-28T00:00:00Z. The conference focuses on the art and science of writing software documentation and brings together programmers, tech writers, support, developer advocates, and more.

Fission will be sending me as a representative from our Developer Success Team. If you are interested in how writers communicate about software, come join us! The conference is in “Portland” but will be held online this year. Hope to see you there!

1 Like

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.

3 Likes

As we discussed in person yesterday - I really like the idea of automating this (to the extent possible). I agree it’s tough to get a team (nevermind outside contributors) to read and adhere to a style guide - so any automation we can introduce to help is :+1:

Thanks for sharing this!

I’ve also been thinking about this quite a bit lately:

But it has been difficult to get the the organizations I work with to adopt this mindset. Collaboration is always a difficult sell it seems.

So, very interested in exploring the resources you shared – thanks again!

Great resources! Thank you for sharing them.

I’m excited to listen to the podcast episode to hear more.