Author Archives: Sarah Maddox

Join the Kubeflow doc fixit at Write the Docs AU conference

Are you coming to the Write the Docs Australia 2019 conference on 14-15 November in Sydney? You’re invited to join us in a two-hour doc fixit on Thursday afternoon, as part of the conference.

Become a contributor to an open source project, learn a bit about how open source works, and help improve the experience of Kubeflow users. All in just two hours!

During the fixit, you’ll add a touch of tech writer shine to the Kubeflow docs. Docs are a super important part of the user experience of any product. Typos and grammatical inconsistencies can spoil that UX. Yet typos and odd syntax creep into any doc set so easily, especially when the doc set is largely written by non tech writers. You can help us set things right.

Where and when

The doc fixit is part of the Write the Docs Australia 2019 conference.

Registration

You don’t need to register separately for the doc fixit. Just register for the conference, then come along to the fixit on Thursday.

Your friendly doc fixit helpers

The doc fixit hosts are:

What happens at the fixit

Here’s how the fixit will work:

  • Before the fixit, I’ll create a spreadsheet with a list of doc bugs that need fixing. They’ll mostly be small things: typos, consistency in page structure, capitalisation, and so on.
  • At the start of the fixit, I’ll give a very short talk introducing the product (Kubeflow) and open source.
  • Then the group will look at the list of bugs and each person will choose what they want to do.
  • My assistants and I will help people create GitHub IDs if necessary.
  • Each person will create an issue in the GitHub issue tracker, describing the bug they’re about to fix.
  • Each person will then update the relevant doc on GitHub and send a pull request (PR) for review.
  • My assistants and I will help people sign the contributor licence agreement if necessary. (A bot will prompt them to do this when they send their first PR.)
  • My assistants and I will review the pull requests and approve each one when it’s ready.
  • The continuous merge/publish tools on the GitHub project will merge the change and publish the update in the docs.
  • The contributor will see their update appear in the docs!

I’ll also prepare a guide to for fixit participants, with the basics on how to work in GitHub and how to update the Kubeflow docs. The guides, in combination with the three of us helping during the fixit, should make the fixit fun and a useful learning experience for everyone.

Prerequisites

Here’s how you can prepare for the Kubeflow doc fixit:

  • Bring a laptop with WiFi capabilities.
  • If you don’t already have a GitHub account, sign up for one. If you have time to do this before the start of the sprint, that’s great. If not, you can do it during the sprint.
  • Sign the Google Contributor License Agreement (CLA). If you have time to do this before the start of the sprint, that’s great. If not, you can do it during the sprint.
  • It’s not mandatory to do any prework, but it will help if you know some Markdown.

References

Join us for Tech Writing 101 workshop at Write the Docs Australia

As part of the Write the Docs Australia 2019 conference, we’re running a two-hour workshop on the principles and techniques of technical writing. You don’t need to be a tech writer to qualify for the workshop, and Write the Docs welcomes anyone who’s interested in technical documentation. Do come and join us!

Tech Writing 101 is a class developed by tech writers at Google to train engineers and others in the principles of effective technical writing. Everyone at Write the Docs Australia Conference 2019 is welcome. For tech writers and others, the class offers an interactive, discussion-filled approach to learning tech writing patterns.

Dates and venue

  • Dates of the conference: Thursday 14 November and Friday 15 November, 2019.
  • Date and time of the workshop: Thursday or Friday afternoon – the conference schedule will show the details when available.
  • Location: Justice and Police Museum, Sydney. See the map and venue details.

Workshop details

Tech Writing 101 consists of two parts:

  • Pre-work that you should read before the class. Don’t be put off! The pre-work is full of interesting patterns and points for discussion: https://github.com/LisaFC/tw101-reading
  • A two-hour workshop at Write the Docs Australia 2019, where you integrate the principles from the pre-work into your writing practices. The interactive format of this class has proved to be an effective way of learning the material. And it’s fun!

Training the trainers: Google is planning to make the course material available for tech writers all over the world who want to run the workshop. You can take part in the workshop purely as a participant, or you can have a dual purpose in mind: take part in the workshop and at the same time observe the facilitator and assistants, with a view to running the workshop yourself sometime in the future.

Your workshop hosts are three tech writers from Google:

Prerequisites

  • Read through the prework, so that you can enjoy discussing it during the class:
    https://github.com/LisaFC/tw101-reading
  • Bring a laptop with WiFi capabilities. (A laptop is not essential, but it makes things easier. During the workshop you’ll write some short pieces and review the work of other participants. Having a keyboard and editing facilities helps.)

Cost (included in conference admission fee)

The workshop fee is included in your conference admission. There is no extra charge for the workshop.

Who’s welcome

All conference attendees are welcome! The workshop is intended for people who want to understand the basic principles and techniques of technical writing. The workshop material is tailored for engineers, and is suitable for new technical writers, editors, UX designers, and anyone else interested in technical communication.

Experienced technical writers are sure to enjoy the content too, both as a refresher and as a reminder of how debatable technical language can be.

The workshop format is highly discursive and entertaining. You’ll find yourself debating the principles as you apply them. The material is designed to stimulate such discussions.

The venue?

No, this is not a picture of the venue. It’s just a building that I found interesting on a recent trip to Prague. I’m also rather taken with the reflections in the windows, showing the windows of the opposite building for a nice Renaissance effect:

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.

%d bloggers like this: