Even Naming This Talk Is Hard

Writers of software and writers of documentation practice a shared art: we bestow abstractions with names. We know weve succeeded when our names illuminate concepts, elicit a-ha moments, and empower users to put our product to work. We know we've failed when the names we've chosen confuse, frustrate, misguide, or offend.

Naming things well matters. Too often, though, good names are hard to come by, and bad names are hard to change.

Using a lengthy and ever-growing list of Terrible, Horrible, No Good, Very Bad names encountered during my career as an engineer, this talk will address:

"You never get a second chance to make a first impression": writing great "getting started" documentation

As the old saying goes, “you never get a second chance to make a first impression”. When you first meet someone new (not least at a conference for documentarians!), those first few moments set the tone. In exactly the same way, the experience your user has when they first “meet” your product and get to grips with it will set the tone for your entire relationship with them.

As documentarians, we so often focus on building detailed and exhaustive “reference” documentation, but in doing that, we forget to provide the right kind of “getting started” experience for a user brand new to our product.

At GoCardless, we spent the first years of the life of our platform focused on building high-quality reference documentation. But in Summer 2016, we kicked off a big piece of work on a new set of resources: a “getting started” guide for our API, getting the user from nought-to-sixty on our developer platform.

To make the right first impression, we had to turn things on their head and think from the reader’s perspective. From this perspective, what we’ll write and build looks very different to our “reference” documentation, seeking not only to teach the user how to use our product, but also to explain the fundamental concepts behind it and to bring the user to the all-important “aha!” moment where they see the value in what we’re offering.

In this talk, I’ll go through:

• the fundamental differences between “reference” and “getting started” documentation

• the lessons we learnt on the way as we experimented and spent extensive time with end users

• what we built

• the results — from our users’ perspective, and in terms of how we build demand within the company for further “getting started” content

Finally! Trustworthy and Sensible API Documentation with GraphQL

View the slides.

GitHub is migrating its public API system from REST to GraphQL. In this talk, I'd like to go over my personal experiences writing API documentation for ten years, and why GraphQL's "everything needs documentation" approach is a much needed improvement. I'd go over past API tooling and methodologies, current best practices to make "sane" autogenerated API documentation, and why I think that GraphQL is a boon for technical writers, developers, and end users.

Telling a Great Story on GitHub

As a former journalist, I tend to think in terms of storytelling. As an open source evangelist, I invite you to do the same. What you share on GitHub tells a story about you, your development practices, and your openness to others in the open source community. If you're motivated to gain users, contributors, and positive feedback about your projects, then building a compelling, coherent narrative is essential.

In this presentation, I'll share insights gained from curating Zalando's GitHub repository so we can tell a better story. I'll describe how we've used GitHub and other tools to create guidelines and processes that bring sanity to our storytelling. And I'll talk about how focusing on higher-quality docs has helped us to instill a stronger product mindset in our development teams. Writing a README, for example, offers an opportunity to tell the world why a project exists, how it works (and why), what makes it unique, and how it might evolve over time. I'll discuss how this process not only empowers developers, but also those of us who are technical writers and storytellers—offering several real-life examples to (hopefully) inspire you.

From 400+ projects of widely differing quality, reliability and maintenance levels, we've winnowed our OSS offerings at Zalando to make our highest-quality work more discoverable and user-friendly. If your organization is facing GitHub-bloat challenges, looking for ways to manage your repos more effectively, or wondering how better docs can help your OSS efforts succeed, you might find some help here.

The four kinds of documentation, and why you need to understand what they are

Nearly everyone agrees that good documentation is important to the success of software projects, and yet very few projects actually have good documentation. Even successful projects often have barely adequate documentation.

Often, it’s not for want of effort - the project’s developers have worked hard on it - nor for lack of documentation - the authors have produced a lot of it.

It simply turns out to be not very good - not helpful enough for the users who should be able to rely on it, and a depressing chore for the authors who have to maintain it.

The good news is that both these problems can be solved by understanding how documentation works, and that there are four distinct kinds of documentation - with four distinct functions. The four kinds of documentation are:

• learning-oriented tutorials

• goal-oriented how-to guides

• understanding-oriented discussions

• information-oriented reference material

Structuring documentation according to its four distinct functions helps ensure that each of them is adequately served. It also makes it far easier to write and maintain.

Using real-life examples I’ll draw out the key functions of documentation, and how they map onto different ways of writing it. Putting this into practice is simple when armed with some basic guidelines. The benefits are huge, and available with a minimum of effort.

I won’t be discussing documentation tools or software or other topics that have been covered amply elsewhere, but some neglected and poorly-understood aspects of documentation that will make your software projects and teams more successful.

Sticks & Stones... Microaggressions & Inclusive Language at Work

You've heard about diversity problems in tech, right? We know the problem exists at every point in the process: education, internship opportunities, hiring. We don't talk much about what happens to the people we do work with.

As documentarians, we spend a lot of time thinking about the best words to use for our products, tutorials, manuals. We know that words matter. "Microaggressions" are the small indignities that people of color, non-cis-gendered folks, women, and others experience on a daily basis. Microaggressions at work tell us, over and over, that we don't really belong in that workplace. So let's talk about the words we use with our coworkers. Let's talk about how we can all make diversity a daily practice at work, not just a hiring problem.

Manage your docs like an archivist

View the slides.

How can you easily retrieve your (google) docs? How can you keep the whole picture in mind?

The first step is to give docs consistent names, but we also need to check our database regularly, and decide what to keep or destroy. What should we base those decisions on? In this talk I’ll give an overview of how you can efficiently handle your docs through the lifecycle model (planning - creating - keeping/destroying) used by archivists/records managers. What is important to keep in mind? How can you organise your own database or that of a company? As a conclusion, I will help you to create a "manage the docs" checklist.

Managing community-driven documentation - how to herd doc-writing cats through motivation and a pinch of automation

Free software projects, community-oriented online services and grassroots technological organizations often rely on volunteer-based documentation, both as regards writing end-user guides and localization. This can produce inconsistencies in style and approaches and, in the end, compromise the usability of the tools or services described in the documentation. There are solutions, like publishing guidelines, enabling volunteer contributions only through git pull requests, or hiring coordinators and reviewers.

During this discussion, we will exchange reflections and tips on the best practices for volunteer-based documentation, so as to start a conversation on how to improve this process in free software projects and in efforts that rely on limited funds but on a strong community of eager volunteers.

Depending on the number of participants, the discussion can take place in one group or be split in smaller groups that will refer to the other participants during the last 10 minutes of the discussion.

Aw Snap! The Docs, They Are A-Changin’ (with apologies to Bob Dylan)

This presentation explores the evolution of language in technical documentation.

The reign of the long-form narrative in tech docs is long gone. Nobody wants to read a 600 page user manual cover to cover before using an application or API. Users crave bite-size chunks of information, and they want them exactly at the point of need. They want just enough information to complete their task and not one conjunction more. In other words, users want high-calorie nutrient-dense documentation, and they want it fast.

To satisfy users, we documentarians embrace minimalism and topic-based architectures such as DITA. We organize content by type: task, concept, reference, etc. We use active voice. We keep sentences short. And consciously or not, we’ve begun to challenge time-honored tech writing traditions, such as prohibitions on future tense, contractions, idioms, and colloquialisms – at least in American English documentation.

What’s more, it’s no longer enough for docs to be technically accurate. They must also use contemporary themes familiar to users and, whenever possible, humor. Exhibit one is this Google Chrome error:

“Aw Snap! Something went wrong while displaying this webpage.”

And the folks at ReadMe.io used this line to describe a Delete button in their interface (from the 2007 film, Juno):

“This is one doodle that can’t be undid, homeskillet.”

Without question, the language we use in technical documentation is changing. Contractions, idioms, and colloquialisms, which were once banned as potentially confusing to translators, are now commonplace, and we use them to make our docs sound friendlier. Jargon abounds, the word “please” is no longer taboo, and exclamation points are not only allowed, they’re encouraged! They show enthusiasm for the subject!!

In this presentation, we’ll mine the docosphere for current trends, innovations, and answers to these questions: • How has the language in tech docs evolved over the past decade, and where is it headed? • What are the minimum daily requirements for language in this brave new world: Correct grammar, complete sentences, parallel construction, proper word choice, clarity, brevity? • What is the role of humor in tech docs? • Is it OK for tech docs to use colloquialisms, idioms, contractions, and even emojis? • What are the implications of this evolution on localization?

Writing a book in 2017

View the slides.

The usual way of writing a technical book is to open the Word or LibreOffice application, to write some content, to make a backup, to send it by email to the publisher and to deal with the feedbacks. And repeat.

However in 2017 we can do differently by using open formats like Asciidoc, by using version control to propagate changes, by using collaborative platforms like GitHub or GitLab to collate feedbacks in any form as well as transforming text and code into readable and interactive artefacts.

It gives us a unique opportunity to approach the whole process of writing in term of "content experience", of "toolchain" and of "distribution".

In the end, a "book" becomes a "writing format" as we can reuse the same pattern to manage any kind of "content" — articles, publications, essays, documentation — that we can transform in physical books, e-books, interactive web pages etc.

Requirements that you didn't know were there

View the slides.

Any doc - every doc - that you deliver, it's only as useful as the requirements it satisfies. Typical requirements revolve around target audience, method of delivery, technical limitations. But after the doc is done, then come unexpected expectations.

Suddenly, your docs should not only make users happy, but also help your stakeholders achieve their aims - move up a career ladder, impress the boss, get a bigger paycheck.

The success of your docs depends on things you are never told. This talk is about reading your stakeholders and deducing the ultimate requirements.

Documentation beyond words

In this presentation I will explore other ways to communicate concepts beyond words to show that documentation needn't just be about technical writing.

In the first part of the presentation I will briefly cover theories and principles behind forms of communication and what documentarians can learn from them. Topics such as:

• Portraying meaning in images: Iconography, maps, manuals

• Non-verbal conversation: Body language, ways of speaking

• Fidelity: Sketch notes, simplicity, style

During each of these topics I will present in the style of the topic, so expect something a little different.

In the second practical part of the presentation I will take elements of the theory and applying them practically. I will start by looking at screenshots and diagrams. When and how to use them, what they should show, and how to manage them.

Then I'll cover taking screenshots to the next level with animated gifs and screen recordings that show clear user flows and expected results.

Finally in this part of the presentation I will cover interactive documentation, and the options for allowing readers to directly manipulate and experiment with documentation and directly see inputs and outputs.

In summary, our work typically appears on one of the most dynamic platforms (the web) that has ever existed, let's all do more with it!

An Alien Looking From the Outside In: Main Takeaways After One Year in Documentation

For 22+ years, I am working in IT – most of this time in the “business-related” part of the game. Roughly a year ago, I decided to change something. Well – still working in IT, and still working in the same company … But I moved from a Product Marketing role (which I hold for about 17 years) to R&D, because the documentation team “made me an offer I couldn’t refuse”.

Of course I interacted with many of our engineers before, and of course I also knew most of the documentation team members before. But in retrospective, I can say that I somehow lived on “another planet” before, and that my first year as documentarian in an open source software company was definitely deeply eye-opening for me.

If you are curious now, join the talk and hear more about my main takeaways regarding documentation in general and the experiences with my team in particular.

Deprecate and destroy: documenting your software’s last days

View the slides.

It could happen to you: your project is canceled, your team is “reorganized”, or your company is closing its doors. Some or all of your software, service, or API may not be long for this world. What will you say to the people using your software? In this talk, you’ll learn how to avoid a communications disaster when it’s time to break bad news to your users.

Whether you’re deprecating significant features or shutting down entirely, you still have a chance to make life better—or at least a little less worse—for the people who have come to rely on your work. In this talk, you’ll learn how to:

• plan your shutdown communications to make sure no users get left behind

• let your users down easy with the appropriate voice, tone, and content

• cope with a stressful situation

From your initial announcement to your service’s last day, you’ll learn how to say goodbye in a way that’s good for you and your soon-to-be-former users.

Tech Writers Without Borders: Making the world a better place, one (numbered) step at a time

View the slides.

Created in 2016, Tech Writers Without Borders aims to connect technical communicators with nonprofits seeking help with their documentation and training materials.

Using examples from our work with iNERDE, a social enterprise seeking to empower West African youth with Science, Technology, Engineering and Math education, I will describe the many ways in which technical communicators can make a real difference to the operational effectiveness of nonprofits and the lives of those they serve.

If you, too, are interested in volunteering your skills for social impact, this session will hopefully inspire you to action, or, at the very least encourage you to view the value of your craft in a new light.

One-on-One 101

In the workplace we experience team-building exercises. The focus there is on many-to-many relationships to help people work well in groups. At the other end of the spectrum we have opportunities for personal development where the focus is on just one individual.

Documentarians inhabit our own special place on this spectrum. It’s clearly defined and, in the world of software development, it’s unusual. We typically work one-on-one with subject-matter experts. Who ever has training for that?

The surprising answer is: “lots of people”. Doctors, for example. Teachers, despite the fact that they normally work with groups. The amazing stewards at my local beer festival. They walk cheerfully into tense situations and leave guests smiling.

We've been left to follow our instincts for too long. It's time to acknowledge this and to discuss strategies for change.

There are valuable things we can learn from other fields.

Hi, my name is README!

View the slides.

When starting a new project, developers, myself included, usually get right into hacking things, like tinkering with libraries, that we would like to learn or solving a particular problem as quickly a possible. Occasionally we also decide to publish the resulting project to a software repository such as PyPI for Python or NPM for Node.js etc., so that others can use our nifty code, submit a pull request and maybe even form a community around the project.

As the creator, you might be lucky and someone will find your project on the front-page of GitHub or maybe eben Hacker News or Reddit. What happens next is on you really. But what does that mean?

Before jumping right to the command line and installing your package, those who are interested usually try to find out what problems the project is solving and how it can help them with their own. That's what your README file is for - it's most likely the first thing potential users read, that you control.

A good README briefly and concisely explains what your software does, how it can be installed and what API it exposes. You also want to provide information on the requirements, the license it uses and how the project is managed. Who are you? How to get in touch to report problems and give feedback? Where can potential users find the Code of Conduct for your project?

This talk is for everyone who is interested in working on open source projects and wants to know how documentation can help newcomers and more experienced users use your code and to encourage them to engage in the community.

A content manager's guide to crowdsourcing the docs

View the slides.

Crowdsourcing is an increasingly attractive practice that is being used to develop documentation. When well designed, this approach increases documentation velocity and reduces bottlenecks. However, there are (at least) two huge challenges:

• Keeping documentation quality high

• Ensuring that content gets developed in line with the products and services it supports

While no doc set will ever be perfect, there is hope for overcoming these challenges. In this talk, I'll share lessons learned from working through these challenges at companies of various sizes. We'll walk through content management best practices, including:

• Setting occasional authors up for success

• Building an effective writing toolkit

• Defining content management strategies for globally distributed teams

You have already succeeded: Design critique guidelines make feedback easier 2.0

View the slides.

Getting feedback on your work is a necessary part of any project, and it makes your output stronger and more diverse. But it can be hard when your work is being evaluated. Sometimes, it feels like your reviewers have a deep and abiding interest in pain. You’ll never succeed! Well, you have already succeeded just by asking for feedback. Together, we’ll discuss how to build up your tolerance for taking that feedback.

Feedback became so much easier for me when I learned design critique guidelines from a co-worker and UX Designer. Design critique guidelines are a set of rules and practices that can make getting and giving feedback easier. After presenting this speech at the Write the Docs Portland 2017 conference, I received a ton of great feedback on it. Now, I have even more strategies to share so that you can implement design critique guidelines into your own review process to make feedback painless.