The Bubble Next Door

On the train journey to Berlin, I watched the first talk of the Write the Docs conference, or WTD for short. In his talk titled Gyarados has pretty teeth, dear, Maximilian Rosin guided the audience through Bertolt Brecht’s alienation effect, Pokémon, and speedruns, all in the service of technical documentation. This introduction alone was as thematically broad, nerdy, and lively as the best conferences are: everything else can be read up on later, after all.

Write the Docs is the world’s largest self-organised TechDoc community concerned mostly with software documentation, but actually encompassing a much broader range of topics. WTD was co-founded by the Eric Holscher in 2013; its Slack server now hosts a good 25,000 users, and topics are discussed with great dynamism. Interested parties can quickly get information relevant to their own work and – almost more importantly – make virtual contact with colleagues in an accessible, low-barrier way. In “real life,” this is possible at events in a good 20 locations worldwide, with between 100 and 2,000 registered attendees each.

With nearly 220 on-site attendees, the event in Berlin’s Kreuzberg district was sold out, supplemented by a good 200 log-ins in a consistently hybrid format. Right at the entrance, I was delighted by the professional, sleeves-rolled-up vibe, the stickers on the laptops, and an atmosphere that, right from the start, felt more like a professional, warm meetup than a “professional,” yet cold congress. Part of this atmosphere came from simple and clearly communicated behavioural recommendations, for example the Pac-Man rule: “Always stand in groups in such a way that there is obviously room for someone else to join.” This was certainly a relief for those who were looking to meet new people but still found it difficult to initiate directly initiate contact.

In spite of, or maybe because of, this playful atmosphere, the WTD community is highly pragmatic and fearless: “The job of a tech writer is to run toward the screaming,” said Val Grimm in her presentation. Instead of trying to manage away the inevitable chaos of reality through processes and structures (sometimes a necessity, sometimes a reflex born of fear), “documentarians” dive right into the thick of it. Because, hey, what else can you do? Software changes much faster than, say, printing presses or combine harvesters. And software and its documentation carries similar, often even more far-reaching responsibilities.

Shared Otherness

Speaking of responsibility: the role called “Documentarian” is defined much more broadly than the one usually assigned to technical writers. According to the WTD interpretation (even the term “definition” would be going too far here), a Documentarian is anyone who cares deeply about documentation and communication, regardless of title or position. This includes developers just as much as, for instance, UX designers or managers. The philosophy behind it is clear: you don’t have to write full-time to be part of the solution; you just have to be interested in improving communication in (here, primarily: software) products.

Through this perspective alone, silos break down. In the traditional sense, writers “own” the docs; in the world of Documentarians, responsibility is distributed. Only a small part of the WTD community consists of full-time writers; the rest come from other disciplines and are exceptionally close to the action precisely because of that. When these different groups then come together as Documentarians, everyone might feel a bit like an outsider: developers who like to document, and writers who like to code. This “shared otherness” creates a bond defined not by tools, but by a common goal: to be understood.

Of course, even in the dynamic software world, processes and standards remain indispensable for quality. The approach, however, differs fundamentally from what is presumably standard for most readers of this magazine. The software docs world has learned (or rather, had to learn) to automate maintenance. It works with linters and tests in CI/CD pipelines, as well as lightweight, rapidly recombinable, and independently customisable tools instead of heavy, proprietary CCMS workflows from third-party vendors.

Without the high regulatory pressure familiar from the hardware sector and with a broader self-conception, they can work more agilely—not least because the stakeholders developing the software are themselves at home in agile methodologies. As a result, topics take the stage at WTD conferences that would otherwise remain in the back seat: the developer experience and radical user-centricity, docs-as-code, and above all essential “soft” skills like dealing openly with issues of team leadership, personal failure, or the status of docs in the overall process.

Ideas from everywhere

Below is a brief look at some of the ideas I took away from Berlin. Some of the talks are available online (for free) so I invite you to watch them.

The problem of fragmented documentation landscapes (for example, following company acquisitions) is all too familiar to many writers. In If you build it, they will come, Ian Cowley outlined the path to a unified platform with a strong focus on discoverability. Unlike monolithic (C)CMS projects, he showed a way to consolidate heterogeneous content from various sources into a central, searchable interface for the user, without having to overturn the underlying processes. Particularly interesting in Ian’s talk was the proximity to hardware: his “docs-as-Product” approach has (long since) ceased to apply solely to pure software documentation.

In Developer Experience in Technical Writing, Michiel Mulders brought the concept of “developer experience” (DX) into play: for developers, documentation must be more than just text. Interactive playgrounds, directly usable code snippets and command-line tools meet users right in their work environment, rather than merely informing them. Documentation transitions from a reference work into an interactive tool that measurably increases user satisfaction.

Outdated documentation is a perennial issue, which Dimple Poojary tackled with rigorous automation in an agile environment. Instead of waiting for manual revision cycles, she showed in Automating Documentation Maintenance Workflow Process for Agile Teams how docs tasks can be linked to developers’ sprint boards and become part of the development cycle. Besides reducing manual labour, this elevates the status of documentation as a necessary component of development.

In A beautiful reciprocal arrangement, Tiffany Hrabusa spoke about the chicken-and-egg problem faced by many young professionals: how do you get your first job without experience – and the experience without a job? The path can lead through the open-source world: there, titles or certifications count for less than the commit. By actively contributing to Open Source Software projects, anyone can get in direct contact with developers and build a portfolio. A stark contrast – and a welcome addition – to traditional paths that rely on academic records, traineeships, and certifications.

Data sovereignty is an essential issue for many companies, especially in the current political landscape. In her presentation called Sovereign Docs, Val Grimm presented how her team “packages” documentation into containers to then deliver it independently of cloud providers and even air-gapped (i. e., without an internet connection). A massive contrast to traditional publication pipelines, showing how docs can be treated and delivered as an independent artefact, much like software.

My personal favourite, both technically and humanly, was Fabrizio Ferri-Benedetti’s talk Failing Well. Documentation is often about managing risks, avoiding errors, and trimming for perfection. Fabrizio spoke about inevitable failure, professional plateaus, texts nobody reads, projects that die, and the emotional labour that ensues. He offered a “field guide” for personal growth that goes far beyond learning new tools, aiming instead to create psychological safety. One example: we often take it too personally when a painstakingly documented feature is scrapped just before release or “starves” in the backlog. Fabrizio advocated distinguishing between systemic and individual failure. It is certainly helpful if writers decouple their self-worth and the perceived value of technical writing from inevitable organisational chaos.

Embracing the complement

I have been writing for tekom and tcworld since 2017, and I’ve been speaking at many events over the years, but always on the same recurring topics: communication, psychology, self-leadership, mindset. With these topics, I am something of a rare bird at tekom conferences; at WTD, such topics are a completely natural part of the programme. Preemptively sorting out the inevitable chaos of reality? Charging into the fire and, with a clear mindset, optimising as much as possible so that the result is precise and helpful? For both approaches, the conference offered incredibly enriching perspectives, a pragmatic-experimental basic attitude, and a great openness to new things.

“It takes courage to advocate for change,” said Ian Cowley in If you build it, they will come. Surely it doesn’t take much courage to look from one bubble into another, but consciously inviting the complementary and seeing mutual blind spots as an opportunity for further development requires genuine openness.

Jennifer Rondeau spoke in What’s past is prologue about the history of various TechComm communities, including Write the Docs and tekom. She emphasised the complementary nature of both organisations: professionalisation at tekom, agility at WTD. The typical tekom discourse provides a foundation for legal certainty, standards compliance, and information architecture; from Write the Docs comes the speed and rapid adaptability of the software world, along with a truly radical empathy for the user’s “Experience”.

In this combination, not only can good technical documentation emerge, but above all a communication culture that is compliant with rules while also delighting users and technical writers alike. We should just get on with it.

Learn more about Write the Docs at writethedocs.org. Joining is free. Local meetups are listed on the website: the organisers would certainly be delighted to welcome tekom members to their upcoming events.

Mathias Maul advises senior management and leadership teams in technical companies on efficient and profitable communication. He studied linguistics and computer science with specialisations in machine learning and AI, and teaches coaching and marketing at universities in Hamburg and Düsseldorf. He has been writing and speaking for tekom since 2016. https://maul.fyi