Spotlight on Write the Docs software documentation community

Did you know that there is a thriving community for people with a passion for software documentation?

Write the Docs strives (and we think succeeds!) to be ‘the most welcoming internet community’. It is focused on the art and science of writing documentation. Members of this group call themselves documentarians, and this can be anyone who cares about software documentation, communication, and their users regardless of job role or title.

While other technical writing communities exist, Write the Docs brings together programmers, writers, support professionals, marketers, and others for a unique mix of linguistic flair, technical expertise, and a passion for great experiences with software.

Origin Story: Bringing documentarians together

Not surprisingly, as many organisations wrongly consider documentation as a fancy extra, doc writers have lacked the community needed to bring their work into focus.

Troy Howard and Eric Holscher founded Write the Docs after they realised there was no community for documentation writers. It was one of those ideas that developed by accident, as the byproduct of an organic need.

There was an existing community of documentation writers in their hometown of Portland, although it never called itself such. Eric and Troy had their first meetup, and decided to take things online.

They say:

“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.”

They set up their website and posted a link to Hacker News, expecting a few dozen sign ups for their conference. Instead, hundreds of people expressed their interest, from developers, to designers, to startups.

Write the Docs was born.

Image: Write the Docs Portland, CC license

Impact: Making the world safe for documentation

Kelly O’Brien, Self-Service Content Manager at Kayako, was formerly a freelance journalist for trade magazines. Her experience maintaining Drupal websites led her into the documentation world and she has never looked back.

For those looking to build their career in documentation, Kelly says, “Join the Write The Docs slack team — it’s such a great community, and an awesome resource whether you’re just getting started doing docs or you’ve been doing it for an age.”

Check out our interview with Kelly for a window into the life of a documentarian.

Swapnil Ogale is a Technical Communicator and organizer of Write the Docs Australia. He says, “Write the Docs has become the tribe that I yearned to be a part of for years while working as a sole tech writer.

“It has given me tremendous opportunities to organise, meet, speak/present and talk to so many people with varied backgrounds, yet all of them love how content and documentation shapes a product/service/app.”

Senior Technical Writer Margaret Eker says, "I discovered Write the Docs at my last job at Rackspace. I wrote a blog post about how Write the Docs inspired our team while we transformed our docs and doc process to a collaborative model based on open source tools."

Roundup: A sampling of our favorite talks

Write the Docs have some amazing talks which they have shared on video for your enjoyment. We’re sharing a small sample of some of our favorite talks relating to all-things documentation. They’re very funny, genuine, and most of all, helpful!

1. Just-In-Time Documentation: Employing Agile Methodology To Create Living Documentation

By Bri Hillmer. Follow her on twitter at @writebriwrite

Bri Hillmer is documentation coordinator at SurveyGizmo and she shares her challenges in her role. In 2014, as the new documentation coordinator, she needed to create a living knowledge base that people actually wanted to use. She also had to switch from “just-in-case” documentation to “just-in-time” documentation.

To start the content-creation process, Bri designed a workflow called Just-­In-­Time (JIT) documentation. JIT is a production strategy that is used mainly in the manufacturing industry to manage inventory supply cost-­effectively. Accounts differ on whether this approach originated in Japan or with car manufacturer Henry Ford.

By applying JIT to documentation, a team can create just enough documentation - just in time. The presentation covers how Bri’s team created this process, refined it and made it a success.

Check out Bri’s blog posts explaining more about JIT documentation and how she implemented JIT at SurveyGizmo.

2. Two Great Teams: Bridging the Gap Between Documentation and Customer Support

By Neal Kaplan. Follow him on twitter at @NealKaplan

In this video, Neal talks about how documentarians can tap into the knowledge of support agents to improve their documentation. In turn, he also explores how documentarians can make the lives of agents better. Documentarians and support agents can team up to provide even better customer support.

User assistance (documentation) is another way of saying self-service customer support. Documentation and customer support both need to work together strategically for a company to succeed.

In short, documentarians can work together with customer support to turn the F in RTFM (Read the F****** Manual) to FANTASTIC! Here’s how documentarians can work together with customer support:

• Review support tickets manually
• Set up automated notifications that alert documentarians to create content
• Review difficult cases and solutions together with customer support agents
• Learn as much as you can about your customers
• Review ticket metrics, and measure how they change as you add more documentation to track improvements
• Have support agents write docs!

3. How to Write Documentation for People that Don't Read

By Kevin Burke. Follow him on twitter at @ekrubnivek

This talk examines the ‘findability’ of your documentation, and the actual text on the pages you write. Usability researchers have known for decades that users don't read online in the same way they do in print. Instead of reading every word, they scan the page for the content they want. In this talk, you can learn more about how users find answers to their questions.

If users can't understand your documentation easily, they'll quickly give up and this results in a loss of revenue. They may also remain ignorant of product features, which is another loss of revenue. They’ll almost certainly ask your team needless support questions, which cost your company more money.

This poses a huge challenge for documentarians, and is one of the reasons that makes this job so exciting. The answer is focusing on the usability of your docs to ensure that users absorb the information they need.

This talk looks at usability research into how users absorb information on the web, ways your documentation might be failing busy users, and lessons Kevin learned conducting user testing at Twilio.

4. Screencasting 101

By Diana Potter. Follow Diana on twitter at @drpotter

In this talk, you will learn about the different types of learning styles, and how this can impact your creation of documentation.

Documentarians can find it tough to admit that not everyone wants to read their carefully written documentation. While people will read some of the time, not everyone learns best by reading the docs. Some people are primarily auditory or visual learners.

Diana aims to make sure her documentation can appeal to as many learning styles as possible. That’s meant spreading her documentarian wings and bridging out from simply writing the docs into recording them as well. She’s been learning how to create screencasts and is now sharing that knowledge with everyone.

Diana covers picking the right topics, outlining, writing a script and recording your audio and video. You don't need to be a professional voice actor or videographer to create a screencast. Even a humble writer can create something wonderful.

5. Engage or Die: Four Techniques for Writing Indispensable Docs

By Kelly O’Brien. Follow her on twitter at @OBrienEditorial

Kelly talks about how to make your technical writing more engaging for audiences. She shares four techniques that she used in her former career as a magazine writer to engage her readers and hold their attention.

When writing your docs, you need to earn your customers’ trust so when they hit a problem with your software, they are inclined to turn to your documentation. This involves knowing who your customers are and how to prioritize their needs. Show sympathy for their frustrations.

The four ‘Doc Deaths’ are:

1. Death by Apathy
2. Death by Alienation
3. Death by Impatience
4. Death by Disorientation

Kelly talks about how to combat these deaths in your docs.

How can I get involved with Write the Docs?

• Slack: The fastest way to connect with the community is to join their very active Slack channel. 
• Newsletter: Sign up for the monthly newsletter and view the archives for interesting information from and about the community.
• Podcast: Check out the new podcast discussions and meetup recordings.
• Twitter: Documentarians are active on Twitter! Follow the hashtag #writethedocs, and follow their twitter account along with other documentarians for 140 characters of documentation-based discussion.
• Conference Videos: Each year, the conference talks are filmed and shared online. Check out their amazing collection of videos on YouTube. 
• Documentation Guide: Check out the Documentation Guide, which “exists to provide both novice and expert writers a best practice handbook for building, structuring, and writing software documentation”.
• Meetups: Write the Docs have regular global meetups around the world. Their meetups take place in various cities in North America, as well as in London, Barcelona, Australia and Seoul, among others. Each meetup is hosted as a local chapter so if there isn’t one in your area, you can always start one! KnowledgeOwl is proud to sponsor our local Boulder, Colorado meetup. 
• Conferences: If you live in an area where Write the Docs host a conference, you can grab yourself a ticket and attend in person. Here is the full list of current and past conferences.
  • Write the Docs Portland, May 14-16, Portland, Oregon
  • Write the Docs Prague, September 10-12, Prague, Czech Republic

Main image credit: Write the Docs Europe Prague 2014, CC licence, by Jiri Folta