Search results

Impressions from the Write the Docs Conference -- and thoughts on achieving sustainability without selling out to vendors

by Tom Johnson on May 23, 2017
categories: api-doc • technical-writing

I recently returned from the 2017 Write the Docs conference in Portland, Oregon. The conference had two days of sessions (Monday and Tuesday), preceded by a day of doc writing sprints and workshops. I also participated in a 5-mile conference hike on Saturday. Although this was the fifth year of the WTD conference (it began in 2013), this was my first time attending. In this post, I'll share my impressions of the conference, contrasting it primarily with other tech comm conferences such as the STC.

Origins of WTD

First, to understand Write the Docs, you must read the origin story behind the WTD conference. In short, a group of developers who write documentation felt a need to get together as a community to discuss best practices and techniques, to share tips and practical guidelines. They weren’t aware of other documentation-focused groups or communities, so they decided to start the conference as a way to help “coalesce” others like them who were also writing documentation. You can read the original manifesto to get a sense of the group’s purpose. Here’s the opening paragraph:

There exists a tribe of documentarians in the world. Up until this point, they haven’t had a central place to meet each other, and coalesce into a community. We are providing the space to allow this to happen, both in person and online.

It wasn’t until later that this tribe learned about other documentation tribes and communities. But even though other tech writing communities exist (like the STC), communities for developers writing documentation for other developers do not really exist. Though the STC does include writers creating developer docs, 99% of the members are not developers creating developer documentation. They are technical writers creating developer docs. There’s a difference.

At the first WTD conference, there were an astounding 250 attendees. This surprised the co-founders and reinforced the need for a documentation community. Now at the fifth year of the WTD conference, the conference sold out with a cap of 600 attendees. They moved into a larger venue, The Crystal Ballroom, and have a host of speakers, workshops, unconference sessions, and other activities for 4 days straight.

Crystal Ballroom

At the center of WTD

The driving force behind the Write the Docs conference is Eric Holscher, one of the co-founders. A Python developer who runs the readthedocs.org site, Eric has open-source principles baked into his way of being. For example, on the trail during the conference hike, as we paused under a visitor shelter during a hailstorm, Eric shared his organic chocolate, carrots, and walnuts in friendly ways with everyone around him.

Eric believes passionately in community and open source, which is one reason for the documentation sprints that precede the conference. Some of his philosophy is inspired from the Python community and other open source movements he participates in.

Eric (and the other WTD organizers) don’t charge much for the conference. A meager $450 (even less for students, independents, or unemployed people) is at all it costs. This fee mostly covers the cost of the venue and food (free breakfast and lunch for attendees every day, including t-shirts for all attendees and hoodies for speakers), some conference management labor and recording efforts, and a little extra to help manage future efforts.

Eric isn’t the kind of conference organizer who sits back at a distance after giving opening remarks. At heart he is a passionate developer who believes strongly in documentation, as do the other co-founders. During the unconference sessions, Eric participates in the sessions, particularly the unconference sessions.

For example, I attended an unconference session led by Troy Howard (another WTD co-founder) about analyzing metrics in repos to compare doc commits versus code commits. Troy wants to gauge the health of a repo by comparing the amount of code commits versus the amount of doc commits (updates to markdown files), correlating it with averages across other repos. Eric joined in and offered his thoughts about the many possibilities for analyzing metrics from the thousands of open repos he manages with Read the Docs.

Eric gets energized in talking about developer docs, and this passion also helps shape the conference. He is fully engaged when he speaks in conversations. He’s also down-to-earth, often walking around with a baseball cap and a water bottle shoved into his back pocket.

More developers at WTD than anywhere else

At WTD, I met far more developers than at any other conference. I had good conversations with at least half a dozen separate developers — people who are earnestly trying to create better documentation. In this respect, WTD contains a type of technology enthusiast most tech writers are unaware of. There are in fact developers who write documentation, who care deeply about creating good documentation systems and platforms, who want to create awesome Hello World tutorials, interactive Swagger API help, and other instructional material for users. This species of the documentation-writing developer thrives in the WTD community.

I also chatted with multiple UX designers and learned from dev support, content architects, and professionals in other roles. This diversity is a key part of the WTD conference, as it points to the belief that documentation isn’t created or maintained by a single priestly class of officially titled “technical writers.” Instead, documentation is created and maintained by a community of people that include a diversity of roles.

One of Eric’s primary goals is to allow access into documentation authoring and publishing for anyone in any role that wants to contribute. This is perhaps why he prefers the term “documentarian” instead of “technical writer,” since a documentarian includes anyone who is involved in documentation efforts. (In contrast, a “technical writer” is usually someone whose chief [paid] role is to write tech docs.)

Defining WTD’s core values

During a doc sprint day, I attended an “API the Docs” brainstorming table with Kristof Van Tomme about potentially holding API-focused events related to the WTD community. These events would be called “API the Docs.”

Eric, who was circulating among multiple groups, also joined in to discuss what he feels must be the foundational principles that define any group or event related to WTD. We talked about open-source, and giving back to the community. Eric gets annoyed when companies take from open source without giving back. We chatted about accessibility, or making the event open to everyone, being inclusive and respectful of diverse roles and lifestyles, and never making events private.

Eric embraces a “Users First” philosophy, where users come first before any vendor messaging that might distort or redirect a conference’s purpose. Despite identifying these values, Eric struggles to define the core values that he feels characterize the WTD experience. He can’t quite put his finger on that undefinable quality that exists at the heart of the WTD community and conference experience. For this reason, he says that anyone who aspires to hold a WTD-type event must first attend the WTD conference.

Eric is very much guarded against vendors controlling the conference. He wants vendors to participate just like attendees. Although the WTD conference had about a dozen sponsors (whose logos appeared briefly on a slide during Eric’s opening remarks and on the conference website), there were only several vendor tables physically present — MadCap Software, Algolia, Google, and WordPress. Of those, MadCap Software seemed to be the only vendor allowed 60 seconds to briefly introduce themselves between one of the conference sessions (though I may have missed the others).

Eric says if vendors want to speak at the conference, they should submit a proposal and go through the process like everyone else. You can’t buy acceptance of your proposal at the conference, nor can you buy time to give a special extended presentation at the start of the conference, neither can you construct a miniature Taj Mahal tent in an expo area (which does not exist) where you might give a stream of microphone-boosted presentations and demos.

If you want to be part of the community, you become part of the community like everyone else — participating like attendees in sessions, interacting and talking with others during breakfast, breaks, and lunch. You have to earn their interest and trust. You can’t buy the email addresses or phone numbers of attendees.

Achieving sustainability in the long run

Despite the aversion to corporate puppetry, Eric worries about the sustainability of WTD in the long run. How can he remove himself from the center of the community so that it doesn’t all depend on him? If something happens to Eric, who will drive the community forward? He is not opposed to paying some people to help manage the community. He knows that generating revenue can be helpful to make a sustainable community organization.

At the same time, he knows this is a slippery slope to repeating the path of the STC. To get revenue, you have to provide an exclusive offering (e.g, magazines, webinars, body of knowledge, salary surveys, etc.). Otherwise, what incentive do companies have to pay money to the organization? Eric doesn’t want community members themselves to lighten their pocketbooks through donations, especially when the knowledge and skills they learn from the conference go right back to companies.

For now, Eric’s strategy seems to be to keep costs low, to not try to grow the community too fast. The WTD venue is in the Crystal Ballroom, which is a historic venue with springy/creaky floors, old heavy velvet curtains, winding hallways and staircases. It’s where the Grateful Dead performed, and where hipster crowds would feel right at home. It is not a super fancy 5-star Marriott or Hilton hotel that functions as a mini-conference center for business conventions.

Perhaps there’s not a need for a ton of revenue to provide the community offerings. The WTD organization shows that you can have a large community conference, with top-notch programs and speakers, including free breakfast and lunch and t-shirts/hoodies and recordings, without resorting to higher conference fees or having extensive numbers of paid staff and an association director.

Unless you’re an altruistic saint, though, you have to get something out of your efforts. What do you get out of all your volunteer time? “Burnout” is an awakening to the imbalance of value. If you find yourself expending a lot of time and effort for little value/reward back, you may one day decide that imbalanced equation isn’t worth it. Eric does benefit by driving more visibility to his ReadtheDocs.com business, which provides hosted documentation solutions (for open source, it’s free, but not for commercial clients). Even so, I’m not sure the WTD community provides much carry over to Read the Docs.

Same challenge is everywhere with online endeavors

In some ways, every online entrepreneur faces the same challenge. I provide free content on my blog. I provide my API doc course for free. I have been writing and publishing content for readers for years, and you have been reading me, without subscribing or sending me money. I provide an “information product” that I give away. Other sites, like online newspapers or journals or other community-based tech writing sites (like Techwr-l), also provide information products for free. How do you maintain sustainability and long-term motivation for your efforts when you give everything away for free?

I’m more open to vendor advertising as a way to support the model of free. I think advertising is the magic oil that provides return while allowing you to keep services free. My sidebar has been showcasing ads for years, and last year I even wrote sponsored posts showcasing new releases or services from advertisers. I view this exchange of advertising for free services as one of the fundamental business models of the Internet. This is how television and radio work. This is how large websites work. Does it mean that I am putting vendors first and my readers second?

I don’t think so, but it does influence my messaging a little. You won’t find me trash-talking any of my advertisers or even my potential advertisers. (Actually, regardless of advertising, long ago I learned not to throw pointed spears towards others from my blogging pulpit, and especially as my audience and visibility has grown, I’ve been careful not to try to undercut anyone or any company with pointed judgment.)

At the same time, I strive for honesty and transparency. No doubt if I stripped away my ads, I might be more free-flowing and opinionated in my posts, letting you know that X is a waste of time, that Y is a charlatan, that Z is a backwards tool that I wouldn’t touch if it were the last tool on earth. But I don’t really do that.

Still, I haven’t been shy about announcing my dislike of DITA, my embrace of open-source static site generators, my shortcomings with the STC and academic research, etc.

I think that advertising does slightly influence the message, but it’s a necessary evil. As long as you don’t overdose or become a vendor junkie, and can keep the advertising as a minimum decoration instead of a driving force, it’s okay.

The most influential ad company: Google

For example, think about the most influential ad company: Google. Every time you do a Google search, Google shows you several sponsored ads. They try to feed you advertiser information. But we tolerate this because Google is an awesome search engine, and they clearly flag the sponsored results. Google would cross the line if they invisibly mixed sponsored results with organic results. Almost no one complains about Google’s ads because we enjoy the search engine so much, we’ll put up with the ads.

Moreover, without any monetary return from ads, Google’s search engine wouldn’t be nearly as awesome or sustainable as it currently is today. Where would Google get the money to pay the engineers, if not through the ad revenue? If left entirely as a free, open-source endeavor, Google’s search engine might have been abandoned long ago. When companies have a financial incentive, users get better products. That’s why we tolerate ads — it’s worth it to get a better product.

However, there is a line companies can cross with ads. Conferences that invisibly mix the vendor presentations with organic presentations cross the line. If you’re attending a conference presentation (or reading an online article), and you can’t tell if the presenter, who works for a vendor, paid money to present at the conference or was allowed to present in return for sponsorship, the conference organizer is doing a major disservice to its attendees.

Has the STC crossed the line with too much advertising driving the conference? Unlike with WTD, the STC conference includes an expo hall with around 75 separate vendors in booths of varying sizes. When I attend STC conferences, I am somewhat immersed in messages about structured authoring and plugging into large CCMSs. Messaging about collaboration through git and open source tooling is less frequent, but it might be due to the tech writer audience rather than any kind of vendor-driven messaging. I’m not sure what the STC conference experience would be like without vendors.

However, one detail that the WTD organizers overlook is that many attendees actually like the expo. It’s fun to see row after row of tech comm vendors with various tools, services, and other wares (it’s kind of like window shopping at the mall, or browsing a festival). You don’t often see these resources for docs or get to try them out and ask the companies all your questions. Vendors aren’t necessarily an evil that you have to guard against. Many of them have created tools to help and support tech writing communities to amplify their documentation efforts. WTD could easily develop more sustainability by allowing more vendors at the conference.

In the end, with the careful protection against vendors at WTD, did I have more epiphanies and realizations than from an STC conference? I can’t say that my takeaways were substantially different. Any time I’m with other tech writers exchanging and sharing ideas, my wheels start spinning and I walk away with a lot of new ideas. Both conferences manage to do that for me, with or without the vendor messaging.

But I admit that I feel more at home at WTD, primarily because there are more topics and attendees working with developer documentation and APIs. The conference is more focused on software documentation, with many opportunities for unconference sessions. I prefer the semi-led unconference sessions over lengthy presentations, even though I, in fact, gave a presentation. I like working with git and static site generators, and this emphasis makes the WTD conference much more relevant to me.

Giving presentations at WTD

Why did I give a presentation? At the last tech writing conference I attended, I didn’t present. I went as a participant only. I ended up sitting and listening to lectures much of the time and concluded that I didn’t like being a bystander. I would much rather present because it means I can interact, shape the conversation, get engaged, and really participate. I’m not a spectator. So I figured if I was going to go to a conference, I might as well present. Upon reflection, though, I might have preferred to just go to the unconference sessions instead.

Presentations at WTD are actually a bit stressful. Unlike the STC, where you have a room of maybe 40-60 participants who consciously decided to attend your topic, with WTD presentations you have all 600 attendees in the room, with only 20 minutes to present. You present on a large stage, with an ear mic attached and your slides projected on a giant screen. Before your presentation time slot, you prep in a green room below the stage and then, when ready, you ascend through an exclusive hallway and stairs to emerge out on the stage, like a performer going to start a rock concert.

To prepare, I actually wrote out a lengthy narrative of my presentation, which you’ll soon see on my site. I felt almost same pressure as I did when I gave a keynote at UA Assistance in Europe, or to tcworld in India. I say this only to help others, who were also stressed, so they won’t feel so alone. One presenter (who was a little red in the face and sweaty) told me she had been out running city blocks as a way to calm her nerves. My guess is that she had run a couple of miles. (Because I’ve given around 80 presentations, I don’t get so nervous in front of crowds, but only if I’m prepared.)

The importance of story

Finally, and I know this is somewhat tangential, I did realize something about myself and presentations at WTD. In my initial practice run of my presentation, I felt something was off. My points seemed to lack interest and structure. It took me a while to identify the issue, but I later realized that my presentation lacked story. As many have said, story really is the essential structure for presentations (see Death by Documentation for great tips on this). Presentations that include story work well; those that omit it fail. It’s that simple. If you figure out the story you want to explore and tell, everything else follows.

I took the 5 design principles I wanted to talk about and reworked them into a story. I was no longer presenting on abstract design principles. I was telling the story of how my users couldn’t find anything in my help, so I set about redesigning my help with these principles to increase findability (which was true). That shift significantly increased the arc of my presentation and made it feel more complete.

Story is something I keep coming back to year after year, realizing that it’s is what interests me or motivates me. By story I don’t mean an interesting anecdote or fiction narrative. By story I’m referring to scenarios where you start out with a tough problem to solve, and then you go about trying to find a solution in interesting ways, exploring different approaches and perspectives.

Finding my form

The focus on story led me to some other realizations, prompted by my conservations with attendees. It seems nearly everyone has read my blog at some point or has found my API course helpful. I am working on converting my API course material into a book, but I’m less and less enthused by book-length content. I want to write more story-driven posts. I studied creative nonfiction in college, and I love the essay format, particularly the interplay between critical ideas and story structures.

I like holding a seashell in my hands for a time, admiring it, finding something interesting about it, and then tossing it back into the sea. Essays are like that. Nonfiction books (especially tech comm books) have a different depth. With books, you take the sea shell home, dissect it, read a shelf of books about it, spend years unraveling every detail, publish your findings in excruciating detail, and then take up a post teaching it for years to come.

Maybe independent blog posts are my form, and I should be content with that. I can say that many more people seem to read blogs than tech comm books. I can hardly walk 10 feet in any tech comm conference without entering a conversation with someone who (recognizing my blog) reaches out to me with an introduction or friendly handshake.

The cool thing about stories is that they don’t have to be long to be worthwhile. Some stories might even be just a few sentences long. There are short stories and long stories. In this post, I have told the story of Eric and his battle to guard the WTD community against vendor messaging while also finding a model for sustainability. I connected personally with my own battle to find a financial return on my blog, and it led it to some realizations that I hadn’t entirely considered at the start. Stories change you when you write and tell them.

Conclusion

One of my favorite fiction authors is John Barth. Barth says that stories are like going on a journey, such as a sailing trip. When you come back, you’re never quite the same person you are as when you left. That’s true for stories as much as it is for conferences.

Next year, will I go to WTD, or STC, Lavacon, Information Development World, Writers UA, or some other conference? I’m not sure. I usually pick one conference a year, sometimes depending on the location and whether I’m speaking.

The good thing about WTD is that although it began as a conference, it’s grown into much more than that. With meetups, Slack channels, podcasts, and mini-events, Eric and other conference organizers have grown WTD into a global community that anyone can join and find a home, regardless of their location, job title, tooling, finances, or other background. Transitioning that initial conference into a global, continuously growing community is truly remarkable.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2024 Tom Johnson