Write the Docs Prague – Day 3 (Summary)


The following write up is about sessions I attended. I spent an hour or so mid-afternoon joining in one of the unconference sessions. A special thanks to Sarah Chambers for sharing her session notes.

After an excellent day of presentations and ideas, I was looking forward to another round of thoughts on writing, API documentation and customer support docs.

In the first talk of the day Pretty Hurts, Riona McNamara explained why better is sometimes better than the best when it came to quality. While it may be looked upon as effective to create documents in vast quantities, the quality of the documents is something that often gets overlooked. We don’t have an established vocabulary to talk about the quality of docs was the essence of her talk.

She spoke about the 2 types of quality

  • Structural quality – Focuses on the grammar, language, organisation and navigation of content.
  • Functional quality – Asks the more pertinent questions such as:
    • Does it do what is is supposed to do?
    • Does it satisfy requirements?
    • Achieve it’s objective?

Functional quality is harder to gauge than structural quality when it came to metrics. How do we achieve this?
a. Understand – State what the document should achieve or is supposed to do.
b. Define – Define functional requirements and get buy-in from internal and external stakeholders.
b. Execute – Create the docs keeping the requirements in mind.
c. Measure – Measure against requirements. Use quality data to communicate impact and value.

Given that almost everyone has used or use some sort of checklists (physical or mental), it was interesting to hear Daniel Beck talk about how he uses checklists in his daily schedule.
His statement “We live in a world where even the best people make mistakes – not because we are bad, but because systems become more complex and expectations increase” made a lot more sense after he showed some photos of flight cockpits and how they have evolved.

  • It is important that checklists contain completable and repeatable actions, instead of merely one to aspire.
  • You should design checklists with some context, such as thresholds or boundaries around what needs to be included.
  • Checklists usually fit a pattern – read-do or do-confirm.
  • Use the checklist to exploit existing habits, reward yourself or log your progress.
  • You can create physical checklists and add movement/sound to make it more dynamic.

Daniel demonstrated how he uses checklists to ensure automation is working by verifying, integrating and prototyping them. It was a very simulating presentation, especially about something we create frequently, but without giving it too much thought.

I am personally an avid reader and fiction is one of the genres I often fall back on to provide some mental stimulus away from work. The presentation by Thursday Bram on What Writing Fiction will teach you about writing documentation thus provided some excellent insight into how these 2 worlds could converge.


This is what there is to writing documentation like fiction:

  • Write what you knowYou’re never going to know everything about your audience and your product. Even if you’re documenting code you wrote yourself, you’re going to learn things from the way other people use that code. Good writing gets a little personal — but you should make an active decision about whether they help the documentation.
  • Be Brief – Good writing is clean and clear.
  • Emotion matters – Instead of just writing out steps in an instruction, try and inspire the readers/users to make most of the inspiration. Use storytelling to add relevance, context and suggestions.
  • Kill your darlings – While we may be tempted to leave clever words in our writing, it is necessary to keep documentation simple and easy to follow for everyone.
  • Provide context – This can’t be stressed enough. Without context, users will have no idea of the why’s and when of the instructions.
  • Set a reading order – Setting a preferred reading order to guide the user.
  • Maintain the CanonThe concept of canon is crucial when talking about fiction series. It’s the idea of the core information that has to remain true over the course of multiple storylines, like where a character is from or which characters are in relationships. Similarly, for our documentation, it the stuff that is based on what’s actually going on with the product or service we are documenting.
  • Encourage fan fiction – “Creating a set of core or canon docs will provide a base for community members to start from, as well as give you a way to denote documentation produced in-house and by fans.” This will assist users on building a community of documentation around products.
  • Use Beta readers and workshops – Similar to creating beta version of software, it can be useful creating beta versions of documentation to gather feedback.
  • Reading and Writing are connected habits – This is perhaps the most important of all. The more widely you read, the better. An article here or a novel there can spark ideas — and I’m not just talking about ideas for good fiction. You can find new metaphors and new perspectives with every word you read. I have found this to be true when I write documentation myself.

Do you know the best people in the organisation to talk about what customers want? Not the trainers, or the developers or even the marketing people. The support staff have more interaction with the customers directly than anyone else combined. Why are we not engaging them with the documentation efforts then? In her thought-provoking talk, Documentarians and Support: Work Better Together, Sarah Chambers gave some great insights into doing exactly this.

  • Technical writers and support staff have exactly the same goal – to help customers perform a task. Technical writers + Support = Superpowers!
  • Support help writers close the feedback cycle perfectly by showing them where the users are having trouble finding docs, are unclear or do not exist.
  • Support can provide writers a lot of information about the users, behaviour, the way they use the product or the language they use

Speaking from her Online Support background, she explained some metrics that support can provide about effectiveness of your documentation (in addition to your doc metrics around page views, engagement etc):
a. Measure your self-service ratios – Self service ratio = (no of article views)/(no of tickets created)
b. Customer effort score – Use a scale from Strongly Agree to Strongly Disagree to respond and look at the distribution of scores (High, Medium and Low effort)
c. Ticket tagging – Tag support tickets by how-to questions (for writers), bugs (for developers) or feedback (for product owners). You can use this data to graph your work effort, distribution of issues.
d. Qualitative data – Make your support tickets topics match your documentation topics. Makes it easy to track and troubleshoot. Also helps with proving ROI on documentation.

How do we get the support team to work with the writers?

  • Use common tools that support can use to create first drafts of documentation
  • Provide them downtime to work on other projects such as documentation
  • Create a in-house style guide as a reference
  • Use the same workflow to progress a document
  • Provide the correct templates to support staff

Kata Nagygyorgy has been working on polling useful data around technical communications for some months now and she provided us with early insights. In an initial sample of 100 responders across NA, EU, AU:

  • There are around 30-40 names our documentarian community identified with, with Technical Writer as the most popular title for documentarians
  • 20% people got into Tech Writing by coincidence
  • Github has quickly grown to be the most popular, with Confluence, Text editors and Word as the most popular tools
  • 71% responders have and use an in-house style guide for their documentation
  • Markdown, XML and DITA are the most popular outputs
  • 66% responders self-review their documentation

You can use this form to fill in your stats: https://goo.gl/6SQc63



I took some time off in the afternoon to network with other attendees and join an unconference table talking style guides.

While the term “unconference” is not new in itself, most conferences I’ve been to in the past, encourage attendees to mingle over breaks.

At Write the Docs, attendees who had an interest in hosting an unconference session could do so by putting up their ideas on a whiteboard at the start of the day and others could join in, providing a break from the intense presentations. I thought this was a real cool way for people to talk about topics close to their heart, be it coding, APIs, style guides, or search algorithms.

I joined in the Style Guides session where a group of attendees spoke about the pros and cons of style guides, what needs to be included/excluded, the “live” nature of style guides and how companies should encourage staff to contribute to style guides.

The key takeaway of this session was: Everyone needs a style guide. It makes life easier, documentation consistent and removes ambiguity around standards.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s