Write the Docs Prague – Day 2 (Summary)


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

After a hectic Day 1 of contributing to, talking about, improving and creating new documentation via the sprint style action, it was time for the presentations.

In her welcome speech, Mikey spoke about how the Write the Docs movement has gained steam worldwide, the main driving factor being the true sharing-and-caring nature of the community. The community is not just about technical writers (even if they form the majority), but anyone who is involved in documenting, be it developers, support, testers or anyone else.

In his very uniquely named presentation Postulating the Backlog Laxative, Paul Adams essentially drew on his experiences to present a case for fitting documentation in a scrum. Coming from a life of playing rugby, he is quite familiar with the word “scrum” and expanded on it to provide some answers on the role of tech writers in a scrum. According to Paul, tech writers are either:

  • Not involved in a scrum, leading to no documentation at the end of a sprint or release.
  • Like a fish riding a bicycle, leading to communication overhead and distraction towards the tech writer. Tech writers could also be spending time writing for one person as opposed to the team, working against the very principles of scrum.
  • Involved in the scrum, but always out of sync by one iteration.

To solve this conundrum, Paul suggested keeping the tech writers out of the scrum, but in constant touch with the scrum team. His rugby analogy of having the tech writers like back runners provided justification that they don’t have to be in a scrum, but just work smoothly with the scrum team.

The 2nd speaker of the day, Istvan Zoltan Szabo provides some great insight with his very timely and needed talk Writing as a non native speaker. For a lot of tech writers in Europe, English is not the native language. Recounting his own experiences, Istvan threw light on the limits of language and how entropy creeps in our communication with using English, as he reckons that English does not have the same preciseness that some other languages provide for. He provided some very good examples to illustrate this point. To counteract this, he explains how he went about pushing his own personal limits, or stretching the borders to quote him directly.

  • Follow a process – Draft, Rest, Self-Edit, then send for review.
  • Stretch the borders of your language – Translate a book, watch a TV series, or get a coach/mentor and practice.

Ever wonder why they ask you to put on your own mask before helping your dependants on an airplane? It may have something to do with being able to make sure that you are in a position yourself before you help someone. In his very offbeat, yet very relevant topic Healthy Minds in a Healthy Community, Erik Romjin spoke about how important it is to identify, talk about and work on our private health in an increasingly connected community.

  • 70% of people regularly experience physical symptoms due to stress, yet they get away by hiding it under the pretext of being “just tired”
  • We are not mental health professionals (as a community), but we make a difference to someone’s well being by simply being empathetic and listening.
  • People love contributing to projects, but we often forget that we need to help ourselves before we help others
  • It is perfectly OK to say NO and it is ok to say NO MORE to things that you are already committed to
  • Suffering through our work serves no one, so it is necessary to let out some of that anxiety and talk to someone.Asking for help is not failing – it is as a matter of fact succeeding.
  • Build a culture that makes everyone feel they are welcome and that you are delighted to have them involved.
  • Show appreciation where due. It can feel uncomfortable to appreciate people, but it is always well received.


Lightning talks

Just after lunch, attendees were invited to present 5-min lightning talks on any topic. Slides were optional, so it was pretty much a chance to present an idea, discuss an issue, provide an answer, or talking about your product/tool/technique.
It was a very cool platform for people to build up confidence or address that stage fright or make a case for a future conference presentation.

If you thought software documentation was a tough gig with multiple approvals and non-forthcoming SME’s, Joan Wendt’s talk Documenting Data Center Operations demonstrated how hard it was to document operations documentation for field staff.

Presenting stories and non-classified artefacts from her work, she explained her workflow on how she went about attending design meetings, working in lab to photograph prototypes, accompanying engineers to first build site, creating draft documents, field testing the documents and then publishing the production versions. For some documents, she was required to get up to 20 levels of approvals before she published the documentation.

Given the nature of the documentation (instructions) and the audience environment (on-field), her documentation sometimes needs to be created with minimalist principles, and with clarity rather than including superfluous text or focus on formatting. Some of the more common challenges she faces:

  • Difficulty in getting knowledge out of some people
  • Strict security policies and up to 20 levels of approvals
  • Detail oriented documentation required.

As with other jobs, there are pros (travel, field testing possible, meeting end users, best practices) and cons (physically demanding, stressful, tedious work) to this type of doc work as well.

Creating meaningful interactions with users requires a strategic voice with a human tone“. In her talk Watch that tone“, Sarah Karp expanded on this quote and explained how voice (personality) and tone (mood) make for a good information experience. She cited some examples of Warby Parker and Mailchimp content that uses the correct voice and tone to guide the user.

In order to keep a consistent voice and tone throughout your documentation, it is important to:

  • Look at your company values and what stands out should be in your content
  • Be bold, optimistic and practical
  • Define your own individual voice

At Atlassian, the Information Experience Designers use something called Voicify cards that have guidelines for different scenarios. It is like a cheat sheet that sets the scene (for the content), provides tips and tricks, a feelings slider scale across the bold, optimistic and practical aspects of the content. It allows them to learn by example and gauge feedback. She summarised her talk with “Voice and tone builds trust – people know you and can identify you!“.

This was my first time at a Write the Docs conference as an attendee and presenter. Drawing up on my experiences (and frustrations) of bad screenshots used in documentation, I spoke about the why and how of screenshots and what we as tech writers could do, to address the issue.


Bad screenshots make a tech writer’s work harder, by adding to the content development time, plus the hassle of getting new and clear screenshots. One way to address this at the very outset is to have relevant instructions around capturing, naming, saving screenshots in the company style guide. Screenshots are basically the most effective when they are used with a specific purpose, be it to educate, complement or guide the user.

Documentoring is a thing, at least according to David Oliver, who uses it to mentor his engineering and marketing team members on the art of producing quality documentation. Documentation needs to be added to the definition of done in a product team. According to David, “documentation is a product. You cannot have one without the other.” This resonated strongly with a lot of attendees.

David Oliver spoke about 2 different cases:

  • Great product/flawed documents – In this particular case, while there was considerable interest early on, users became frustrated with the product particularly around difficulty in using the product. It became difficult to retain users.
  • Simple product/better documents – While the product was easy, users could get into all the features and the feedback was around improvements. Documentation made it a very good experience for the users.

In order to give yourself the best chance to succeed, it is crucial to use the same toolset (JIRA, Markdown, Github) as other teams. Also, sometimes it important to have documentation at 80% correct than 80% complete.

The key to good documentoring is: persistence, process, events, empathy. And donuts. They always seem to work.


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