Author
Mano Toth
Senior Technical Writer
Recently, I had the incredible opportunity to attend the Write the Docs conference for technical writers in Portland, Oregon. It was a trip of many firsts for me: my first time at the Write the Docs conference in person, my first trip outside Europe, and my first transatlantic flight. For folks who circle the globe twice every morning before their first coffee, this must sound pretty ordinary. But for me, what an adventure it was!
An icy flight
My trip started with a stunning 14-hour flight from Vienna, soaring over the Arctic Circle. This route took me past the icy expanses of Iceland and Greenland. Flying so high and far north, the world below seemed a sprawling canvas of ice and rock, a rugged wilderness as far as the eye could see and as long as I could stay awake. As I have only travelled in relatively densely populated Europe before, I have never truly appreciated the vastness of space in more sparsely populated regions of the world.
A sweet arrival
Arriving in Portland, my first thing to do — under strict orders from my wife, a chocolate taster and educator — was to explore the city’s renowned chocolate shops. Portland’s lively chocolate scene did not disappoint, offering an array of unique and delicious tastes that were a perfect welcome treat. If you end up in Portland, do try out Woodblock Chocolate’s amazing hot chocolate from their own bean-to-bar blend!
Exploring Portland and making connections
Before the conference officially started, I joined a group of fellow documentarians for a half-day hike in Forest Park, the largest urban forest in the US. It was a fantastic way to connect with peers and get a feel for the city. Contrary to my expectations, Portland proved to be rather walkable. I was pleasantly surprised to find that I could cross the Willamette River on foot via the Hawthorn Bridge and I could return to my accommodation by tram, challenging my preconceived notion that moving from one place to another in America practically requires a car.
Photo of the hike by Eric Holscher.
Docs as tests
The conference kicked off in earnest the next day with the writing day where we collaborated on different documentation projects. For me, one of the standout projects was the Docs as Tests initiative, led by Manny Silva and supported by Niko Berry. They've developed a tool that allows you to specify tests and run them directly from the documentation source, ensuring that the procedures and screenshots you describe in the docs accurately reflect the product. It’s a brilliant direction, though not without its challenges, such as integrating a graphical user interface and more straightforward methods to run the tests in products that require the user to log in using SSO or similar.
"Photo of writing day" by Kay Smoljak is licensed under CC BY-NC-SA 2.0 DEED.
Docs as delight
Dennis Dawson’s presentation on visual strategies in documentation was particularly inspiring. He pushed the boundaries of traditional tech writing by advocating for documents that aren't just functional but visually appealing and delightful to read. His talk sparked a lively debate about making humor and creativity accessible in technical writing, especially for readers from different linguistic and cultural backgrounds. This is a topic we have been discussing as well at Axiom, whether and how the company voice can be conversational and even fun while remaining widely accessible.
Docs as code
Another significant theme from the conference was the Docs as Code approach, the reasons for its ascendence, and its side effects. To me, this is about bringing documentation practices closer to software development, using similar tools and methodologies. This approach is meant to foster a more integrated and collaborative environment with faster release cycles, enhancing both the quality and consistency of technical content. One of the unwanted side effects is that Markdown, a language never intended to be used in documentation projects at scale, became the de facto standard in documentation source files to the detriment of more structured markup languages with a much steeper learning curve such as DITA.
Taylor Krusen’s talk explained how MDX, a format that allows you to import React components to Markdown files, has recently been gaining popularity, and the challenges this presents. In short, MDX lets you make documentation more interactive and dynamic, but it means your documentation source files run as code, making the whole edifice liable to break with shorter notice than technical writers are used to. Taylor presented Markdoc as an alternative solution, a document format that enforces a strict separation between code and content, thus addressing some of the issues associated with MDX.
Docs as key
Another great talk was from Michelle Irvine who talked about the DORA project that studies software delivery and operations performance. Among other things, it measures what counts as good experience and what its elements are. The conclusions were music to technical writers' ears. It turned out that, when it comes to developer experience, the number one differentiating factor is documentation. Everything else is secondary to that. The most impact you can have on every aspect of developer experience is good documentation. This is something you might expect intuitively because if you tell people how to use something, they have an easier time using it. Nevertheless, it’s good to have some data to back this up.
Unconference sessions and spontaneous discussions
Aside from the scheduled talks, the Unconference sessions were a highlight. These informal discussions allowed for more personal interactions and were a hotbed for spontaneous, insightful dialogues across a wide range of topics.
Post-conference adventures
After the conference, I seized the opportunity to explore more of the US, venturing as far as the majestic Redwoods. Driving down the stunning Pacific coast, stopping to dive into the ocean now and then, and walking among the towering redwoods was nothing short of magical. These are places I've long dreamed of visiting.
Final thoughts
The Write the Docs conference was more than just a professional gathering; it was a journey of personal and professional growth. It brought together a community of like-minded enthusiasts, eager to explore new ideas and challenge the norms of technical writing. I left Portland not just with new insights and new friendships, but also with a renewed sense of wonder for the natural beauty and human creativity that surrounds us.
