Sarah Maddox's Blog, page 4

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.

Date and time: Thursday, 14 November, at 1pm.
Location: Water Police Court, Sydney.

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:

Sarah Maddox (that’s me: Kubeflow tech writer at Google)
Alec Glassford (Tech writer at Google)
Riona MacNamara (Tech writer manager at Google)

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

Details of the Kubeflow doc fixit on the WtD AU site.
The Kubeflow documentation site.
The Kubeflow docs source on GitHub.

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:

Sarah Maddox
Alec Glassford
Alexander Koren

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:

[image error]

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:

Localisation of open source docs, by Zachary Sarah Corleissen
Empathy in support documentation, by Plamena Maleva
Mapping user experience, by Aaron Collier
Tech writing in developing nations, by Prerana Pradhan
Docs as code and the UK government, by Jen Lambourne
The language of data privacy, by Karen Sawrey
API docs before the API exists, by Ben Ahmady
Docs for startups, by Brian Lemke
The perfect error message, by James Scott
The writing process of Grammy-winning artists, by Kayla Lee

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:

Slides: The story of a doc sprint, by Sarah Maddox
Blog post: How to run a doc sprint

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!

[image error]

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:

[image error]

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

[image error]

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

[image error]

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:

[image error]

Looking aft:

[image error]

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:

[image error]

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:

[image error]

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:

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.
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.
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.
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.
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.

WtD Prague: Docs as code and the UK government

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.

Jen Lambourne’s talk was titled, “The UK government meets docs as code”. Jen is head of technical writing at Government Digital Service (GDS) in London. Her team manages all their docs (internal and external-facing) using docs as code.

Docs as code is the practice of applying software development tools and processes to technical documentation.

At first glance the processes of docs and code look similar:

Docs: Write -> edit -> review -> publish
Code: Write -> review -> test -> deploy

Jen’s presentation showed us how the above process flows are actually not that similar. You’re faced with plenty of unexpected scenarios, and you need to make decisions in those situations.

User research

User research showed the docs were performing poorly.

There were no technical writers yet. A new tech writing team was in the making. Developers wanted to contribute to the docs, but could not. The docs used proprietary tools and PDFs for which the original source was lost.

Experimentation

The team ran an experiment to see if the docs as code tooling would work for them. Initial results were encouraging.

But scaling is important in a project the size of a UK government department. And funding is a problem always.

Getting the tooling

Faced with the decision on whether to hire a tech writer who knows code, or to beg help from an in-house engineering team, Jen’s team chose to ask for help from an engineering team. They traded skills when asking for help: if you help us with git merging, we’ll help you with how to write a blog post.

Repository

They chose GitHub as the location for their docs source. That’s where the developers store their code.

Handling stakeholder feedback

When stakeholders became anxious and asked why the tech writers weren’t focusing on the content rather than the tools, Jen’s team had to choose whether to refocus on updating content, or finding out more about the stakeholder’s concerns. They chose the latter, and showed the stakeholder how an improved tool set would lead to improved content in the long run.

Static site generator

Jen’s team chose Hugo over Jekyll, because Hugo has plenty of templates. But soon they discovered that Hugo wasn’t right for them because it’s written in Go and GDS doesn’t have much experience in Go.

So they went back to the drawing board, reassessed their options, and chose Middleman (written in Ruby, which GDS has experience in).

Doc repository

Should the docs be in the same repository as the code, or in a separate repository? Jen’s team chose a separate repo for the user-facing docs, while internal docs go in the same repo as the code.

Separate repos as best for findability and access control.

Continuous or manual builds

At first the team decided to trigger the docs build manually, but later moved to continuous integration (CI). Jen recommends CI.

More decisions

Jen talked us through many other decisions that faced the content team. For example, do you choose single- or multi-page design, do you convert docs that are in other formats, do you do the conversion by script or by hand, do you use a linter or rely on reviews to enforce style, and more.

There’s still work to be done, but even at this stage the team has seen plenty of benefits. Developers contribute to the docs, support tickets and complaints are way down, and the docs processes is usable.

My takeaway: automation is key, but it takes time and you may need to reverse earlier decisions to work better with automation.

Thank you Jen, this was an amusing and informative story about docs as code.

WtD Prague: The language of data privacy

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.

Karen Sawrey presented a session titled, ‘Disagree with “I Agree”. Enforcing better data privacy through the language of documentation’.

Karen started with an overview of GDPR  (General Data Protection Regulation) and its intention to protect the privacy of all people in the European Union. She talked enthusiastically about how GDPR helps ensure better security.

GDPR targets obscurity in language. GDPR defines two types of data: Personal data, and personal sensitive data. Lack of security in personal sensitive data can lead to severe consequences for the person involved. Karen talked about insecure password policies, and how you can find out if your credit card has been hacked.

Tailoring documentation and playgrounds to better GDPR compliance

Karen divided docs into two types: docs that tell the user something, and docs that interact with the user, often asking them for information.

For the first type, informational docs, you need at least a privacy policy and a cookie policy. When you add interactivity, you include registration forms and agreements. You need to make sure the language is clear and simple, so that people understand what they’re agreeing to.

GDPR says that documentation must be concise and informative. Keep the language simple.

Users must give explicit consent for the specific usage of each piece of information that they supply. As a result, you end up with a series of check boxes asking for the user’s agreement on specific items. At the same time, you must take care not to overdo it with too many checkboxes, says Karen.

If you offer sandboxes (sites offering the ability to experiment with your software), keep the user data in the sandboxes clean. All user data must be encrypted, according to GDPR. Keep the sandboxes isolated, so that it’s harder for hackers to steal data.

Make sure your documentation clearly shows the location of your privacy policy and other privacy resources.

Collect only the information that you need.

Thank you Karen for a lively glimpse into privacy regulations and their impact on the docs.

WtD Prague: API docs before the API exists

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.

Ben Ahmady’s talk was “Write the API docs before the API exists”. The topic was DDD: docs driven development. Ben works at a company that has an API consisting of RESTful endpoints. The users are developers and program managers.

The project

When Ben joined the company, they wanted to design version 3 (v3) of the API. To start off, they examined the problems that users were experiencing with the v2 API. They talked to product support and sales engineers, and looked at API logs and support tickets, to identify the pain points.

As well as identifying pain points, they wanted to make the API simpler to use: Simpler endpoint structure and request bodies, and default behaviour that was closer to user expectations.

Should a tech writer be involved from the start of a new project, at design stage? Ben pointed out that there are some disadvantages. For example, the design may change and the tech writer’s time thus may have been wasted. There are advantages too. For example, tech writers help ensure the design is consistent across different parts of the API.

Docs driven development (DDD)

The goal was to design a part of the API, and open it up for feedback in time windows. That is, provide a short period of time for feedback, then go back to design, and iterate.

They used GitLab for managing the docs (Slate) repository. Continuous integration (CI) was built in. Ben discussed some of the technical details. He also showed us the simplified requests that people can send to the v3 API.

Feedback on the resulting docs is positive. The team has also conducted some user research on the usability of v3. Some people find the docs important, but others prefer using Postman nearly entirely for experimenting with the API.

Conclusions

Overall, the project has been successful so far:

Feedback is good.
The use of GitLab CI and review apps has been very helpful, and will also be useful for future projects.
The docs are ready to go at the same time as the API.
The designers can focus on the whole experience.

Less positive aspects:

It’s still difficult to get feedback from users.
It’s hard to maintain v2 at the same time as v3. Ben has had to make the same change in each version of the API.
Sometimes it’s hard for people to see what’s changed, so the team has to describe the changes made.

Ben and the team are planning much more user research and further design iterations. They’re also investigating new ways of getting user feedback.

Ben has learned a lot about various technologies, such as the OpenAPI spec, testing in different languages, such as Java, and GitLab CI.

The takeaway for writers is:

Plan carefully, and don’t be afraid of the tech!

Thanks Ben for an enthusiastic look at a cool, exciting way of developing docs and API at the same time.