Write the Docs Prague conference 2017

Write the Docs is an inclusive community for technical writers and anyone else interested in the wonderful world of documentation.

I went to the September 2017 Write the Docs conference in Prague on behalf of KnowledgeOwl. I learned all I could about the latest in writing documentation, and met lots of interesting people.

The weekend began with a boat tour along the Vltava river through the center of Prague. The conference itself was held in the Autoklub hotel. It included both formal presentations and lightning talks by community members.

Writing day

I spent time in a team creating a documentation module for developers attending a coding bootcamp. The idea behind this project is to educate developers about the importance of writing docs for their software projects, at as early a stage as possible.

It’s much easier to influence the priorities of new developers or those purposely upskilling themselves at a bootcamp, compared to seasoned developers with little interest in documentation.

If a software project has been around for some time, it can be much harder to go back and document what you’ve done. This is the foundation of the ‘docs like code’ approach popularized by Anne Gentle. She even published a book on it.

Following on from the Writing Day was the main event: a two-day conference discussing all things documentation. We’ve summarized a collection of our talk highlights from the conference, although there were many more fantastic discussions.

Each talk was recorded, and you’ll be able to find them on the Write the Docs YouTube channel soon.

The four kinds of documentation

Daniele Procida, Community manager at Divio, kicked off the first talk with a discussion of the four kinds of documentation.

There are:

• Tutorials
• How-to-guides
• Explanations
• Reference

Each different type of docs needs to be kept separate. These categories are useful for documentarians in all fields, but are often overlooked by developers.

Unfortunately, “Most software projects have bad, poor or missing tutorials.”

Image: Daniele Procida

Many people make the assumption that there is only one kind of documentation, which is that of straight reference, but this couldn’t be further from the truth.

As Daniele says, “There isn’t just one thing called documentation.”

All four types are necessary to document your code or any other product. “You can’t force people to use your software if it’s not documented well,” says Daniele. Or as the popular phrase goes, “Docs, or it didn’t happen.”

Daniele asks, “Why is it that programs crash so much more than planes?” The answer is because pilots do nearly everything properly, unlike programmers, and it’s unthinkable for the documentation for pilots to collapse into an unusable mess.

“The bad news is you’re probably doing documentation wrong. The good news is, doing better documentation is actually much easier.”

Tutorials are comparable to teaching a child to cook, and must be kept practical with an immediate sense of achievement. Reduce the number of choices for the learner as much as possible. Avoid theoretical discussions that aren’t necessary to complete the task.  

For example, here is a Getting Started tutorial from KnowledgeOwl. It’s aimed at users who are the most unfamiliar with our product, and intended to help them get their account and first knowledge base set up as quickly as possible.

How-to-guides are more advanced than tutorials, and are aimed at walking the user through completing specific tasks. They tend to answer questions that complete beginners probably couldn’t formulate, and are comparable to a cooking recipe.

How-tos and tutorials are more suitable for users while they’re actually coding. References and explanations are better for when users are studying.

rixx has done an extremely thorough write-up of this talk over on their blog.

Writing great ‘getting started’ docs

Tim Rogers, software engineer and documentarian at Gocardless, is right when he says, “You never get a second chance to make a first impression.” This means your ‘getting started’ documentation should be of high enough quality to engage your users to start using your product.

Image: Tim Rogers

Developer docs in particular have a bit of a reputation for being formidably difficult to understand, especially for beginners.

Gocardless had this in mind when they decided to review and revamp their API documentation for their current and potential users. They realized that while they very much liked their own docs, they weren’t as effective as they could be for newcomers.

After much consideration, Tim’s team realized, “If we’re going to build better documentation, we need to ask the right questions.” These include who is using your documentation, in what context, how often, and why.

It’s a common mistake to focus more on your organizational priorities than the actual people who will be using your products. Tim says, “Our role as documentarians is to be advocates for our users. We need to avoid the trap of thinking our users are wrong, or stupid.”

Gocardless also had to measure whether their docs were effective or not. “Your docs should take your user to their magic moment,” Tim advises.

To achieve this, you need to find out who your users really are, and, “There’s no substitute for testing your docs on new users.”

Taking inspiration from the Stripe docs, which is an ecommerce platform, their redesign focused on readability, and letting the content shine through as much as possible.

“It’s unwise to try to write one piece of documentation to meet every need,” Tim advises, since this will dilute the usefulness of your docs.

The most memorable quote of Tim’s talk was to “simplify aggressively”. Cut everything from your docs that isn’t absolutely necessary for your users to understand your product well.

A content manager’s guide to crowdsourcing docs

Becky Todd is a Senior Developer Experience Writer at Atlassian. It took her a while before she realized that she longer personally wrote the docs. Instead, she has developed into a content manager and editor, but held onto her role as a documentarian.

Image: Becky Todd

“People read docs in the context of a task,” says Becky. “Imagine reading your favourite reference docs on a lazy weekend. You wouldn’t.”

This means you have to deliver the right content, at the right time, in the right context, to your users. This will maximize the chances that your docs will benefit them.

So how should you deliver the docs?

“I frequently hear complaints about poor docs preventing developers from doing their jobs, but no one is that keen to do anything about it,” says Becky.

Her aim at Atlassian was to provide a watertight process to help their community to crowdsource the docs, and distribute responsibility among many. Becky says, “Crowdsourcing is leveraging the marginal interests of people to complete a task.”

The ideal way to crowdsource your docs is to identify a willing pool of volunteers, and assign someone the role of overseeing the process (in this case, that’s Becky).

This approach has both benefits and drawbacks, which Becky outlined in her talk. For example, the writing you get may not of as high quality, but you can streamline the process by offering a template for contributors to fill in.

A few more points from other great talks

“There’s no current guidance on using emojis in your docs.” Kate Wilcox

“Are we moving towards junk food docs?” Ie Ones that are written for users with a short attention span and need for entertainment? Kate Wilcox

“Use positive humour in your docs that doesn’t rely on put-downs to be funny. It’s less likely to offend people in your audience.” Kate Wilcox

“Much of what we make is an extension of something made by somebody else, an exercise in making things with other people’s code.” Ruthie Ben Dor

“Descriptive naming is hard because it’s reductive. We find it hard to know what to exclude.” Ruthie Ben Dor

“Everyone in your organization being too busy can indicate a lack of clear direction and strategy.” Laurita Apple

“Busy can be used as a status symbol, indicating heroism and feeling important.” Laurita Apple

“We love to publish, hate to edit.” Laurita Apple

“Help developers to see the person they’re developing for.” Laurita Apple

Social media from the conference

Fantastic tweets from the conference also provide insight from the community members present at the conference.

Here are just a few highlights:

A panoply of feelings about product (and docs) deprecation, expertly articulated by @ddbeck. #writethedocs pic.twitter.com/2k52uVzIfr

— Kelly O'Brien (@OBrienEditorial) September 12, 2017

"Words [may be harder to write than code as they] don't compile neatly into binaries." - @hackebrot #writethedocs pic.twitter.com/CmV6vn5sc2

— Karen Sawrey (@krnswry) September 12, 2017

Bad names confuse, frustrate, misguide, obscure, offend. Good names contextualize, explain, illuminate, empower. #writethedocs @unruthless

— R.Trommer (@indigo423) September 12, 2017

 You can view all the tweets using the #writethedocs hashtag on twitter.

Final remarks

There are lots of fantastic photos from the Prague conference on Flickr.

KnowledgeOwl is very happy to be a sponsor of Write the Docs Portland. I’m glad I could attend Write the Docs Prague very easily from my home in Manchester, and get to meet so many new and seasoned documentarians.

KnowledgeOwl offers dedicated knowledge base software to help you write your best support documentation. Take us for a free spin today.

Images credit: Write the Docs