Write the Docs Prague 2019 wrapup

This week I attended Write the Docs Prague, in the lovely city of Prague. While at the conference, I blogged about some of the sessions and spoke to many interesting people. This post is a summary of the event, with links to posts about specific sessions.

Write the Docs is a community of people interested in technical documentation. The heart of Write the Docs is a series of meetups in various parts of the world. There are also a few annual conferences in Australia, Europe, and the US. You don’t need to join an organisation. Just join a meetup, and then turn up.

Write the Docs focuses on documentation rather than on technical writing. The community explicitly welcomes anyone with an interest in technical documentation, including technical writers, engineers, UX designers, editors, and more.

The haps at Write the Docs Prague

This is the sixth year of European Write the Docs conferences, and the fourth time the conference has been held in Prague. There were approximately 300 attendees this year – the biggest year yet.

These are the notes I took from some of the sessions I attended:

Lightning talks tend to go a little fast for note-taking, so I didn’t blog about them. Thanks to everyone who gave a lightning talk. They were entertaining and informative. I did one myself about doc sprints:

The venue

Write the Docs Prague took place at the the Autoclub Prague (Opletalova 29, Prague 1). The outside of the building looks a little forbidding, but if you look closely at the doorway you’ll see a welcoming sign: Write the Docs Prague: You made it!

The building originates from 1929. It’s an automobile club, and it also hosts dances and music concerts.

Inside is all colour and style. This is the main hall, looking towards the stage where the talks happened:

The next view looks from the stage towards the back of the hall:

Being an autoclub, the venue has a few interesting bikes scattered around. These two are Harley Davidsons, manufactured during WWII:

The pre-conference boat trip

The pre-conference boat trip has become a tradition for Write the Docs Prague. Around 70 documentarians boarded for a two-hour trip up the Vltava river. That’s an L not an i in Vltava. Evidently the name comes from the Old Germanic wilt ahwa, which means wild water.

Looking towards the bow:

Looking aft:

The Vltava river runs through the centre of Prague. Eighteen bridges cross the river in the city. One of them is the historic Charles Bridge:

The next photo shows the Jiráskův bridge, with a view of the Dancing House (the skew white and grey building) beyond the bridge towards the left of the photo:

Thanks

Thank you to the organizers, speakers, and attendees of Write the Docs Prague 2019. The conference was a lovely experience. The highpoint for me was meeting some interesting, quietly amazing people.

WtD Prague: Localisation of open source docs

This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.

Zachary Sarah Corleissen‘s talk was titled, “Found in Translation: Lessons from a Year of Open Source Localization”.

[From Sarah Maddox, author of this blog: Localisation is the process of translating content to different languages, and of adapting the content to take regional idioms and linguistic customs into account.]

Zach’s experience comes from localising the Kubernetes docs.

Advantages of localisation

Zach discussed the advantages of localising an open source project. Localisation opens doors to a wider audience. It’s a tool to drive adoption of a product. Localisation also offers the opportunity for more people to contribute new features to a product. It therefore distributes power within the open source project.

When the Kubernetes docs managers considered localising the docs, they made some assumptions that later proved to be unfounded. For instance, they thought the localisation contributors would contribute only to their language. That proved not to be the case. Localisation contributors update the English source as well as their own language source, and they also help other localisation teams get started. For example the French teams help other teams get started with localisation infrastructure, and groups of related languages get together to define grammatical structures for technology-specific terms, such as “le Pod”. Thus the localisation contributors embody the best of open source contributions.

Localised pages increase the number of page views, which is a good thing for a doc set. Zach showed us some stats from Google Analytics with some impressive numbers. Each language added around 1% page views, which represents a big number in a doc set as large as Kubernetes.

Zach said we should also consider the support ratio that the localised docs provide. For example, there are 8 localisation contributors for the Korean docs, catering for 55,187 readers. So, 8 : 55,187 is a ratio of 1 : 6,900.

Advice

These are some of the nuggets of advice Zach shared:

  • Let each of the local teams determine for themselves how they create the localised content. That fits in best with open source philosophy, and the local teams know their local customs best.
  • The Kubernetes project does require that the localisation teams adhere to the Kubernetes code of conduct, and that the code of conduct is one of the first docs translated.
  • Bottlenecks include infrastructure, permissions, and filtering by language. You need to put solutions in place to manage these bottlenecks.
  • Trust is essential to collaboration.
  • To make it possible for a high level of mutual trust, make sure the boundaries are clear, and be careful with the permissions that you assign in the repository.
  • Choose a site generator that has strong multi-language support. A good one is Hugo. Jekyll makes things very difficult.
  • Filter the issues and pull requests by language. Zach doesn’t know of any good tools for this filtering. (If you know of any, shoot him a tweet.) Zach mentioned some possibilities from the Kubernetes world: Prow is a possibility but it’s a heavyweight tool for just localisation. Another option is zparnold’s language labeler.
  • Use version control to review and approve by language. Require review and approval from a user in a different company from the submitter of the pull request.

Some cautionary tales:

  • Look out for raw machine-generated content.
  • Make sure the translators are not being exploited as free labour. Even if you’re not directly engaging the translators, take steps to ensure ethical content.

Thanks

I learned a lot from this session. It was especially relevant as we’re starting to consider localisation of the Kubeflow docs which I work on. Thank you Zach for a very informative session.

WtD Prague: Empathy in support documentation

This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.

Plamena Maleva’s talk was titled, “The Power of Empathy in Support Documentation: A 5-Step Guide”.

Empathy and design thinking

Empathy is the ability to understand and share the feelings of another. But the kind of empathy that Plamena is talking about is more related to the methodology of design thinking. The first stage of design thinking is “empathize”. You need to walk in your user’s shoes so that you can clearly define the problem you need to solve, rather than just assuming you know what the problem is.

Design thinking relates to the creation of a product, and documentation is a product. Plamena used a help centre as the example in her presentation. A product is something designed to solve a particular problem. Therefore, a help centre is a product too. It requires innovative processes to design and maintain.

Support documentation needs to please many parties: users, founders, designers, developers, and ourselves.

Plamena says the definition of empathy should be seen as relating to users, but also to the product and support teams, including the writing team. If you look at it that way, you design the docs with a holistic view.

The process

How do you go about designing with empathy? Plamena presented the following steps:

  1. Start small. Draft the key articles for your help centre first. Come up with the most general use cases, write those up, then link to the basic step by step guides. Then delve deeper in the next step.
  2. Include all the perspectives. Listen to product owners, developers, your own team, and of course the users. Define the key people and key teams, contact them and get their feedback. Do this at the earliest stage possible. Make sure that the customer support articles are designed for the end user. Show your work to people who have used the product as well as to people who have never seen it before. Also show the work to your stakeholders (developers, product owners) to ensure it meets their requirements too.
  3. Build the infrastructure. Define all the feedback touchpoints and link them in the way that makes sense for your product. Empathize with the developers and your team of writers, to set up the tools that everyone needs. The help centre should belong to everyone in the company. Important channels in the infrastructure: Backup of the feedback received so that you can share it with the team, reporting user feedback, collecting internal feedback.
  4. Monitor all the incoming feedback, from all relevant channels. For example, look at customer satisfaction ratings for each article. Follow the reports from the product team about new features and update your docs accordingly. Monitor incoming support tickets, and edit the docs accordingly.
  5. Iterate. Be open to the possibility of changing the initial idea in response to feedback. Plamena says you should think of this as a way to view your entire writing process, not only a particular document. Approach your work as if it will have to change within a relatively short period, as the environment will change. Plamena mentioned that we don’t have a definite “conclusion” phase for tech writing projects. Some people feel a lack of fulfillment as a result. By adopting the open, iterative mindset, the lack of a conclusion doesn’t bother us.

Plamena closed by saying that documentation is a constant work in progress, and this applies to all aspects of our lives. The journey is essentially the destination. With that philosophy, we can apply empathy to ourselves.

Thank you Plamena for an in-depth look at designing support docs with empathy.

WtD Prague: Mapping user experience

This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.

Aaron Collier’s talk was titled, “Seeing your docs through different eyes: Mapping doc users experiences”.

Aaron asked the question, “Why do we document things?” He suggested the following answer: “To help people understand how to achieve their goals with specific tools”.

If we’re trying to help people, we need to understand their goals: what they want to achieve and how they express their needs.

The situation before running user experience (UX) research

Aaron explained how the docs team worked before they started the exercise in UX research.

Most of the input was from developers.

The tech writers were maintaining and adding to existing documentation.

The team didn’t have much direct contact with users or ways to get direct feedback on the docs.

They didn’t work with the product outside their own context. They knew how it was meant to work, and didn’t try to use it from other perspectives.

User experience mapping

The docs team initiated a process derived from the UX discipline. The user experience mapping process is based on customer journey mapping, but maps how people interact with the product. In this case, the product is the docs. The goal is to focus on the touchpoints – where the people interacted with the docs and what their goals were.

The team wanted to understand the entire experience, and how it made the users feel. The context of a person’s feelings can affect their reaction to the touchpoints and the situation they’re in.

Aaron showed some examples of experience maps. A map is based on a timeline, and shows the person’s feelings at each point in the timeline.

The experiences you have at the beginning and end of a timeline are the ones that contribute to a lasting impression.

How to do doc experience mapping

Doc experience mapping entails the following steps:

  • Gather information about the readers. Break the data into categories.
  • Create personas for the readers. These are representations of the users, based on your data categories to help you work with the personas. The goal is to have empathy with each persona, so you give them names, desires, and smiley faces.
  • Meet and go through the journey of each persona.
  • Take action based on the results.

The docs team had plenty of help from the UX team, and melded information from other sources such as analytics, support tickets, and the marketing and sales teams.

Aaron’s team came up with six personas for the docs. He walked us through a couple of the personas.

Next, the team created a map for each persona. The map is based on a possible scenario, and takes the form of a timeline showing what the persona is doing at each point, and how they’re feeling at that point. The timeline starts before the person comes to the docs. Colour coding shows the touch points with the docs.

Working through an experience map

After creating the experience map for each persona, the team worked through the map, discussing the touch points that were not related to the docs, and working through the docs in detail for the doc-related touch points.

While walking through the maps, the team learned a few things. For example:

  • The persona is unhappy before they come to the docs.
  • Every page is page one. The persona doesn’t start at the top and read through the docs. They go directly to the doc they want. The team discovered they needed to add more information to the page to take into account that it’s the first page the persona is seeing.
  • The first example is far too complex.
  • A “Try it” button is not easily visible.

Taking action

The team adjusted the pages to fix the issues discovered when walking through the maps. For example, they made the “Try it” button more visible, and made the examples more consistent.

Some articles started negatively: “You can’t do this”. That does not lead to a positive experience. So the team made sure the article started with a positive experience: “You can achieve something”.

The team also discovered they needed some less technical articles for people who were just getting started with the product.

Aaron noted that this is an iterative process. The team will be doing the UX mapping again soon.

Thank you Aaron for an inspiring insight into UX mapping for docs.

WtD Prague: Tech writing in developing nations

This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.

Prerana Pradhan‘s presentation was titled, “Fostering Technical Writing in Developing Nations”. I’m very interested in this topic. Building tech writing skills around the world is a goal that’s close to my heart.

Prerana is based in Nepal. Prerana graduated as a software engineer, and joined a company in that role. At the same company she took on a few different roles. Part of her work involved writing user manuals. She didn’t have the role of tech writer, but she enjoyed the work. Then she applied for a position as a tech writer at another company.

At first, Prerana was unsure about making the switch in role from software engineer. The role switch was unusual in Nepal, but Prerana really enjoyed tech writing, so she decided to go ahead. In the last six years, the tech writing team at her company has grown from one to six tech writers, and Prerana is now the lead of the tech writing team.

Teaching

An opportunity came along to teach undergraduate students about tech writing. Prerana was uncertain of her ability to take on this work, and was also unsure about the time commitment. But she went ahead and accepted the challenge.

Her fears proved groundless. Prerana found that she enjoyed sharing her real-world experiences with the students, and she was able to teach pretty well.

After the first year of teaching the 101 course in tech writing, the university asked Prerana to develop and teach the 102 course as well, with a focus on the language and disciplines of technical communication.

Bridging the gap

In her work at the university, Prerana discovered that computing students were unaware of tech writing as a viable career option. Some of the students had good writing skills and when they learned about tech writing, they were willing to pursue the career after graduation.

Prerana sees academic internship as the way of bridging the gap between the universities and the companies that employ tech writers.

Prerana has given talks at meetups about believing in yourself. People come up to her afterwards to discuss tech writing as a career option.

In Nepal and other developing nations, STEM (science, technology, engineering, maths, and medicine) careers are in demand, and there are also more and more tech writing jobs being advertised.

Working in an organization

Prerana recommends building a team structure that promotes collaboration rather than hierarchy.

Hiring strategy is important. Few people have the required tech writing skills, so Prerana recommends hiring people with aptitude rather than looking for existing skills.

Prerana’s team also promotes internal skill-sharing sessions, where they discuss topics like DITA, minimalism, copyediting, and other tech writing topics. One of the goals of these sessions is to be aware of what’s going on in the rest of the world.

Challenges

Technical writing is often neglected, especially when deadlines are pressing.

Stakeholders believe that tech writing is something anyone can do.

Prerana noted that everyone in the organization needs to understand that tech writing is part of the development process and needs to be done in the correct way.

Reasserting tech writing as a career choice

A few years back, Prerana was having doubts about her choice of tech writing as a career. So she did some research and attended some conferences, including LavaCon and now Write the Docs Prague. This was an eye opener to her, to hear about the lives of hundreds of other tech writers.

Prerana realized again that she really enjoys this role.

Future goals

Some goals to focus on:

  • Continue collaborating with educational institutions and other companies to promote tech writing.
  • Participate in conferences and meetups.
  • Spread the word about tech writing. Do anything that triggers a conversation, and see what other tech writers are doing around the world.
  • Expand your skill set.

Prerana expressed her thanks to everyone who has helped her directly or indirectly in her journey.

Thank you Prerana for an inspiring story about tech writing in a developing nation.

%d bloggers like this: