Impressions from my first Write the Docs meetup

by Tom Johnson on Nov 8, 2014
categories: technical-writing

I attended my first Write the Docs meetup last Thursday night in downtown San Francisco. It's interesting to compare Write the Docs with the STC. (I was downtown at an STC SF meeting just the previous month, if you recall from an earlier post.)

What are my impressions? In general, the Write the Docs crowd is younger and more tech savvy. Many of them work for small companies or startups, and they may be the only writer or play a hybrid role of engineer/writer or support/writer. Because of these hybrid roles, the host used the term “documentarian” to refer to a broad grouping of people who are involved with documentation but may not be official technical writers.

Two presenters each give 30 minute talks, and they both ended on time. The presenters got straight to the point without long autobiographical slides about who they were and other belabored introductions. Many of the examples they showed involved code samples, with tips such as making sure to include helpful information in error messages, making sure users have the right context and setup to run the code samples, avoiding PDFs to improve search results on Google, and more.

Check out Kevin Burke's presentation here: How to write documentation for users that don't read.

While watching Kevin's presentation, I thought about how I liked the focus on content. It's so easy to get distracted into other topics outside of content development, such as tools and platforms, agile methodologies, content strategy, etc. These presenters focused on how to create good help content.

There were also some writers from larger companies, such as Atlassian and Splunk. One Atlassian writer created documentation for Bitbucket. But I'd say in general, most Write the Docs writers don't work for large companies.

The food was free. The space was generously donated by Fastly (a CDN company), and it was just 2 blocks from the downtown Caltrain station, making it extremely easy to get to. They even had a bike rack inside the building! (Had I known that, I wouldn't have parked at the Caltrain valet station, which closes at 8:30pm.)

The people tend not to have egos and are particularly friendly. One presenter, Greg Koberger, talked about ways to make documentation more dynamic and reactive. His presentation lasted 25 minutes, and he didn't even mention or demo the amazingly beautiful API cloud doc tool that his company just created: Readme.com. I was stunned.

This developer/designer said he has been obsessed with documentation sites and has browsed thousands of doc sites just looking for elements that work well. He showed how inserting the user's authorization key or other credentials dynamically into docs so users could grab and run functional code snippets was essential in creating good docs. He challenged the idea that a doc site needed to be separate from a company or project site.

The meetup drew about 45 attendees, and they showed up about 30 minutes before 7pm and socialized until the presentations. The hosts ordered pizza and provided free drinks for everyone, and a couple of people (who work for Atlassian and Fastly) mentioned that their companies are hiring.

The only person I knew at the meeting was Andrew Davis, a well-known recruiter for tech comm API jobs in Silicon Valley. After the meeting, Andrew said "Isn't it refreshing?" So many new faces, enthusiasm for good documentation, energy and excitement.

It's hard to think of Write the Docs without comparing it to the STC. Why not create simple groups on meetup.com that gather monthly at company spaces, order free food for everyone, and provide engaging yet brief speakers?

I talked for a while to a writer/support person about her company and role. She worked for a startup with 13 people. A designer created their help site. It allows you to test your own API calls and monitor your API responses. The site is beautifully designed, open to the web, and rebuilt daily from scripts (you can see it here: runscope.com/docs). There isn't a database backend -- it's a flat file architecture, custom-built rather than leveraging an existing CMS platform like Drupal or WordPress. The writer/support person writes in Markdown, uploads to Github, and the daily builds refresh the site. The doc site blends seamlessly into the rest of the company site.

What about single sourcing scenarios? I asked. What about pushing the same content to multiple channels, which often requires an XML architecture with docs? In the small company with a single product, this wasn't an issue.

Andrew later commented that if more of these Write the Docs types of writers faced scenarios that required single sourcing, they would develop technical strategies for it.

Interestingly, Eric Holscher from Read the Docs (based in Portland) recently tweeted:

Is there a good explanation of why single sourcing for documentation is a good thing? Preferably something w/out much jargon. #writethedocs

— Eric Holscher (@ericholscher) October 30, 2014

Perhaps in the developer space, single sourcing is a rare need, not enough to justify adopting an XML architecture with specialized transforms.

Overall, Write the Docs might be how the STC should be. Perhaps the STC started out in the same way -- groups of young, like-minded people getting together spontaneously, choosing speakers with insightful things to say.

At some point, the STC transitioned toward chapters and bylaws and governance. Now there are official staff and the monthly chapter meetings go on for 75 minutes or more (sometimes longer) with one speaker. Presenters are sometimes vendors. The worst is to attend a tech comm conference and not be able to distinguish vendor presentations from non-vendor presentations.

Don't get me wrong. I like the STC, and I manage the meeting program for the Silicon Valley STC. But part of me longs for a time when get-togethers were more innocent and spontaneous. During my undergraduate years in college, I belonged to a group called Wick's End. We got together on Friday nights and hung out and actually read poetry -- either poems we had written or ones we liked. I was also part of an underground newspaper that also had a somewhat free structure and meeting schedule.

Sometimes I think about creating my own meetup of like-minded people who want to hang out and talk about tech comm, sharing our experiences, problems, frustrations, etc. I'm not sure why we think that we always need a presenter to fill the time. There is plenty to say and do without a formal presentation.

For example, when I was in Utah, before the STC chapter there dwindled into oblivion, I planned a meeting where we sat around a table and shared the biggest problems we faced. Then we talked about solutions for those problems. One of the participants said it was the most worthwhile meeting she'd been to.

Despite the benefits of meeting and connecting with others, going to any meetup is generally time-consuming. To get to the meetup tonight, I left work early, rode the Caltrain into the city (1 hr ride), then rode it home (1.5 hrs), not counting the bike rides to and from the Caltrain (30 min). That's about 3 hrs of travel for 1.5 hrs of meeting time, and it takes up the whole evening (wife, kids -- see you tomorrow).

Are meetups worth it? Sure. But you know what has partly replaced meetups? Blogs. A good post on a blog with threaded comments can be like attending a meetup in your own space at your own time.

I'll continue to attend both STC and Write the Docs. It's not that I'm learning a tremendous amount. Most of us know what we should be doing (we just don't have the time to implement it). I attend because I like meeting with other technical writers in my area. The face-to-face social element is almost impossible to replace virtually. And it is especially refreshing to attend Write the Docs, to meet people with fresh ideas, who aren't tainted by long-held traditions and out-of-date tools. This crop of new writers can help move the profession forward without even realizing it.

Check out more at WritetheDocs.com to see if there's a meetup in your area. Currently there are meetups in Portland, San Francisco, Boston, and New York. If there's not a meetup in your area, you could always start one.