I attended my first Write the Docs conference last year, in Portland. I’d been passionate about documentation and knowledge sharing at work for many years, but I’d been a professional documentarian for only about six months. It was therefore galvanizing and inspiriting to be surrounded by hundreds of like-minded people, people creating a community with strong and clear values that resonated with me. This community is incredibly friendly, warm, inclusive, egalitarian, supportive, helpful, friendly, and thoughtful. That’s one of the primary reasons the conference was extremely valuable for me last year, and why I was eager to attend again this year.
I hope sharing my highlights from the conference will be helpful to anyone working on software documentation or considering attending a similar event.
On Saturday I joined the annual conference hike. This was super-enjoyable and a great way to meet new people and have interesting conversations in a beautiful environment, while being active.
Sunday was a community writing day for documentation sprints. I skipped it so I could drive out to the Pacific coast and walk in the surf. It was a beautiful drive, a beautiful beach, and a restorative experience.
On Monday the only talks in the main hall that I attended were the introduction by Eric Holscher and the first talk, by Heather Stenson; I spent the rest of the day preparing a lightning talk (see Tuesday) and attending unconference sessions.
The main conference started with a wonderful introduction by one of the founders of Write the Docs, Eric Holscher. This was an introduction in the most expansive sense of the term — he went to great lengths to encourage a warm, welcoming, supportive, inclusive community.
Stenson presented Any friend of the docs is a friend of mine: Cultivating a community of documentation advocates. Great talk all around. My favorite aspect of this talk is that it’s about an idea that’s somewhat obvious, and has been discussed before, but it took a fresh approach to the topic. Stenson focused on very concrete and practical ways of running an actual program designed to manifest, maintain, and harness a diverse community to work on an org’s documentation.
Forming a non-profit
Clay Murphy generously shared his purpose and experience in working to form his non-profit FirstRides.org which teaches underprivileged young kids how to ride motorbikes in a safe, supportive, and accessible environment. I was moved by Clay’s story of how switching from a car to a motorcycle enabled him to cut his costs enough to stay in college, and how he wants to help others take advantage of the radically lower costs and higher efficiencies of riding motorcycles as compared to cars. This struck me as an extremely timely idea, as the combination of the climate crisis and growing financial inequity mean that we have a doubly urgent need for people to switch to more efficient modes of transportation.
Real tech writing in confluence: Rock the Docs
Matt Reiner kicked this off by showing a website he’s been working on with a few other people: Rock the Docs, which is intended to collect and organize tips and techniques for maintaining “real” technical documentation in Confluence. (My impression is that Confluence tends more often to be used for wikis and knowledge bases.) Impressively, the site is itself authored and published via Confluence — it essentially is a publicly viewable instance of Confluence. The site is impressive and looks like it’s full of highly-accessible tips on working in Confluence, some of which are probably applicable for any usage of Confluence. Discussion of the site and its contents evolved into to a far-reaching exploration of the challenges related to using Confluence for technical docs — both internal and external.
How to set up auto grammar/style checks with Vale
I showed up late to this one, and when I arrived the crowd gathered around Jodie Putrino was the largest I’d ever seen for an unconference discussion. There was intense interest from the group in Jodie’s experience adopting Vale, a “free, open-source linter for prose built with speed and extensibility in mind.” That description is from Vale’s website, which continues with this useful explanation of its value proposition: “Unlike most writing aids, Vale’s primary purpose isn’t to provide its own advice; it’s designed to enforce an existing style guide…”
Being a command-line tool, Vale seems perfect for a team employing Docs as Code, as Jodie’s does (she spoke about her team’s experience adopting Docs as Code at Write the Docs Portland 2017). For example, Vale could be run via an editor integration, as a Git hook, and/or as part of an automated test/build pipeline. In fact, that’s exactly what I did when I integrated Vale into my FLOSS diagramming framework only two weeks later.
Show and Tell: Docs as code framework for architecture diagramming
I proposed and hosted this discussion; I wanted to share the FC4 Framework with an eye towards hopefully growing the community of people using it and maybe even contributing to it. About eight people attended, which I thought was pretty good given the demographics of the conference (which have shifted over time to be dominated by technical writers). It was encouraging that my short demo was effective; it seemed that the participants really understood the value proposition of the framework and found it compelling.
I’m a big fan of the lightning talk format. Whether they’re five minutes or ten, accompanied by slides or not, they tend to be very effective and efficient at making people aware that something exists, and giving them enough information to determine whether or not they want to learn more. Since “x exists” is often the most important and impactful result of a conference talk, lightning talks probably have the best bang/buck ratio in terms of discovering new ideas, tools, topics, and techniques to bookmark and investigate later.
Torretta’s talk Succeeding as an Internal Engineering Writer… was extremely relevant to my interests. He discussed the significant, and potentially surprising, differences in priorities between internal customers and external customers. For example, internal customers don’t care about consistency of presentation.
Needham’s talk Comics in Docs was fun, engaging, and compelling. As a mega-fan of comics I didn’t need any convincing, but I was delighted to see someone using comics to show when, why, and how comics can be used effectively as a form of documentation.
When someone asked me what I’d thought of the first talk of the day, I was dismayed to realize that when I’d glanced at the schedule over coffee that morning I’d somehow missed the talk, called Draw the Docs. If I’d noticed it in the schedule I would have made sure to have attended, as based on the title alone it was extremely relevant to my interests.
I therefore made sure to download the talk (using the excellent youtube-dl), and I was eager to watch it on the flight home — which I would have done, had my laptop not been dead.
Once I was able to watch the talk, I was even more excited. Raszkowska is an engaging speaker, and the talk is beautifully constructed. I had proposed a similar talk entitled Docs as Code for Architecture Diagrams wherein I would have focused on the benefits and the workflows involved in diagramming software architecture using a text-based notation. Raszkowska covered nearly the same topic, except for the focus on architecture specifically. (Which makes sense given this audience. Documentarians frequently need to explain what a program does, and how it does so — which means workflow or data-flow diagrams are crucial.)
The talk selection committee definitely made the right choice; whereas Raszkowska started by telling the compelling story of how and why she came to integrate drawing and graphical documentation into her work and only then moved on to her more analytical segment on automation and workflow, I probably would have started in the analytical mode and stayed there. I’m grateful to have learned so much by noting the differences between Raszkowska’s talk and mine. I suspect that if and when I do end up delivering my talk it will be substantially more effective than it would have been, had I not seen her talk.
Reiner presented Show Me the Money: How to Get Your Docs the Love and Support They Deserve which was a comprehensive guide on how and why to achieve and maintain alignment between “the business” and the documentarians. His energetic, humorous presentation style breathed life into a topic that is crucial but can be dangerously dry. This is a talk that I’m definitely going to be re-watching while I take notes.
Because this was a sponsored talk I was initially concerned that it might be more than a lightly veiled recruiting talk for MacNamara’s employer. I should have had more faith in the conference organizers; they wouldn’t waste the community’s time like that.
MacNamara’s talk Documentation for Good: Knowledge as a tool for equity and inclusion was inspiring and galvanizing. She helped put words to some beliefs I’ve long held in in a hazy, inarticulate way — that making knowledge shared, open, and accessible is an act of radical egalitarianism that fundamentally levels the playing field. Knowledge is a form of power, and I believe that people shouldn’t have more or less power due to the happenstance of, for example, their age, tenure at an org, or level of experience in their career (nor of course their race, ethnicity, national origin, marital status, parental status, gender identity, disabilities, neural differences, etc).
MacNamara’s talk comprised a powerful and useful blend of ideas and information and I expect to revisit it a few times so as to internalize both.
Parsons’ talk Lessons Learned in a Year of Docs-Driven Development was an extremely informative case study in her org’s continued embrace of docs-driven development. I was first introduced to this idea by Tom Preston-Warner as Readme Driven Development, and I’d thought that he’d invented the idea, so I was grateful that Parsons led with a short history of the idea that questioned that story.
Decorah’s talk Automated Testing for Prose was impressive and
inspiriting. I now aspire to adopt and employ something like Mapbox’s
copyeditor system. (It’s a
alex, and now I’m curious to compare
Friesen’s talk Don’t get RSI was informative and heartening. It’s reassuring to be around people who clearly care about their communities and who go out of their way to support the wellness of their communities — people who have enlarged their circle of empathy.
My Lightning Talk
I hadn’t been planning to give a Lightning talk. During the hike on Saturday I was describing literate programming to someone, and I mentioned that I tend to use Git commit messages to tell the story of my work. The person I was speaking with was intrigued to learn that Git commit messages have an official format so I described in in some detail. Eric Holscher overheard and said something like “sounds like a lightning talk!” — which sounded good to me.
So I spent some time on Sunday, Monday and Tuesday preparing a talk. My talk was chosen as an alternate for Tuesday’s batch of lightning talks, but there was no time for me in the end. The organizer of the lightning talks, Rose, suggested that I present the talk as an unconference session, so I did that.
I ended up calling the talk Storytelling with Git (slides). I enjoyed putting the talk together and delivering it to a small but highly engaged audience in an unconference session. It ended up being ~15–20 minutes rather than 5, but that included some discussion.
Another highlight of the conference, for me, was the effort and attention put towards inclusion. It was heart-warming to see and made me proud to be part of this community.
I ❤️ Portland!