Accessibility (a11y) has been finding its stride in the web development community ‐ and it’s not hard to figure out why. According to the World Health Organization, there are over one billion people globally who need an assistive device. With these statistics, organizations and open source projects alike realize that they could be unintentionally locking these people out of their products. As a result, they adjust their developer workflows. And it often ends there, at the product. Documentation is left out of the conversation.

If documentation is meant to serve as a tool for learning and comprehension, then it must be included in those conversations. After all, we want to write docs that are truly for everyone ‐ regardless of the technology they use to read it.

In this talk, we’ll look at how assistive technology consumes documentation and cover some points to consider when building out your docs. Along the way, we’ll touch on quick regulation wins and inclusive writing practices.

I’ll be talking about an area of technical writing that’s not particularly glamorous, and tends not to get much love: the humble release note.

When I joined my current company back in September 2017, I noticed we didn’t have a consistent format for our release notes, and they were often clunky and difficult to understand. And when I did a bit of research to see if there were any generally accepted formats, I was surprised at how little guidance I found.

I realised I had plenty of my own ideas about what made a good release note (from reading and writing many over the years), so I gathered them together and gradually formed them into a style guide. Drawing from this, I’ll talk about:

• making release notes easier to write ‐ and read ‐ by grouping them into categories and then using templates to write them
• how you can improve readability with a few simple style tweaks
• viewing release notes as a ready‐made opportunity to show your users the hard work you’ve put into your product ‐ the bugs you’ve fixed, and the suggestions you’ve listened to

In a world of legacy content, how do we resolve the issue of technical debt in our documentation?

As technical communicators, it’s very easy to get caught up in the cycle of moving from one release to another without taking time to refine what already exists. Trying to keep up with documenting new features means we often find ourselves navigating though outdated and disused stylesheets/labels/files/content/junk in projects that we inherited from technical communicators before us and haven’t had the time to clean up.

If this sounds familiar, then this presentation is for you!

It aims to help you tackle the daunting task of cleaning up your project and getting rid of technical debt once and for all. We will cover:

• What is technical debt, how does it accrue, and why should your organisation care
• How you can tackle your debt and give your documentation project the spring clean it needs
• Tips for staying debt‐free

A year ago (or so) BuzzFeed realized we had a documentation problem. Our docs were kept in numerous places, from Google Drive to Wikis to Github folders to...places we may not even have found yet! In response we started a working group called The Better Docs Project, with the mission of organizing, standardizing, and completing our documentation.

During this talk we’ll go on a narrative journey through the first year of Better Docs, talking about what worked for us, what didn’t work, what we’re excited to try next, and the lessons we’ve learned (and friends we’ve made) along the way. I’ll share actionable tips for how to steal our experience to get your own projects and workplaces on the road to Better Docs.

Imagine for a moment that documentation is the face of your product. How much concealer would you put on it?

The majority of people would likely agree that no product is ever perfect. When it comes to software, the jokes about bugs practically write themselves. Should the product documentation acknowledge this, or should it cover up the imperfections? In some cases, the answer seems obvious, but what about those situations where there is a major known issue - or five? How should the person in charge of documentation address this? Should they just stick a big warning into the release notes, or point out the problem and offer a quick workaround in the documentation itself?

This is not only a content issue, but also a question of ethics. It is a challenge that has come up time and again in my personal (albeit short) career as a technical writer, and I suspect many others have faced it, too.

This talk will look at some strategies that writers can rely on if they decide this is an issue worth considering. Important aspects that will be covered include:

• the tone and language used when addressing product shortcomings
• communication with stakeholders, product managers and other subject-matter experts
• dealing with clunky or unintuitive UIs and workflows that are not officially recognized as issues, but are still impeding the user experience and understanding of the product

To install, simply do [these several steps]! If you’re like me, you’ve written lots of documentation like this. We all want our products to be simple. Worse, lots of us believe our products are simple. But trust me, they’re not simple! Your installation guide failed on step 2, and I don’t know how to fix it! In this talk I highlight some writing styles which seem innocuous when written, but which show a lack of sympathy when read. I suggest some ways to avoid these pitfalls and bridge the gap with your reader.

How do you prove that docs are key to growing a software business?

Documentarians have long struggled to get buy-in from stakeholders and win more budget because the impact of docs on a company’s bottom line has never been clear.

Things like traffic analysis, at best, tell you whether customers are facing a recurring problem, or if they’re finding your docs easily. Article ratings also help you understand if customers find your docs useful. But to prove that docs actually impact your bottom line, you need to dig deeper.

In this talk, I’ll share new models I’ve designed to help measure if your docs drive customer growth:

• What would your company look like without docs? (A basic control for measuring success)
• Do your docs help win new users? (Acquisition-focused attribution)
• Are users who read your docs more likely to take the key steps to become customers? (Activation-focused attribution)
• Can docs help convert new customers into loyal advocates? (Retention-focused attribution)

I’ll demonstrate how you can apply these models to your business, with both theoretical and practical advice.

The journey, benefits and shortcomings of writing runnable documentation. A story behind the "documentation is code" principle and how it saves money and time, empowers documentarians, simplifies processes around testing documentation and brings happiness to a diverse customer base.

My team developed software that was used as part of a medical product. We used modern development practices and tools to document the code and the APIs exposed by our microservices, but was that enough?

This talk introduces the audience to the particularities of developing medical device software and the regulatory landscape that you must comply with. I’ll focus specifically on the processes and culture that enables the creation of medical software device documentation intended for auditors, without damaging (too much) the team velocity and spirit.

There’s a long history to text markup languages, and I don’t think most people know much of it. This talk gives a quick overview of the major formats, including nroff/troff, SGML, HTML, Docbook, TeX and LaTeX, setext, reStructuredText, markdown and AsciiDoc.

In passing, I shall complain briefly about the history of wiki markups, and explain my reservations about markdown, and why it’s still a good thing.

The slides, and extended notes, will be available at https://github.com/tibs/markup-history.

I love my job. My title is "Information Architect", but that’s mostly because "She Who Figures Out What We Need To Do About Our Documentation And Does It" is too wordy for HR. I work in a product unit of about 350 people creating software for developers, very few of them skilled writers or native speakers of English. My role is to figure out how we can produce good documentation.

I have a problem of scale: I can’t do all of the technical writing we need. So instead, I’ve become a contagious documentarian. Over the last year, I’ve infected taught technical writing to over 200 people around my company. My 3 1/2 hour course, "Technical Writing for Techies", is popular, and seems to be effective. There’s been a noticeable improvement in the writing we’re producing, and (even better) an awareness that good writing is an achievable, even enjoyable, thing.

When I describe the course formally, I tend to list attendee objectives such as:

• Think about the audience and how to write for them.
• Study and practice different writing techniques.
• Understand and use a style guide.
• Learn ways to improve word choice and sentence structure.
• Study the commonest mistakes that non‐native speakers make in English and how to correct them. (etc)

And I do cover all of those topics. But just between us, my real objectives for my students are:

• Stay awake.
• Feel welcome and relaxed enough to participate openly.
• Finish the course feeling competent and capable about writing.
• Trust the Information Architect enough to come to her with future problems.
• Want to be part of a community of documentarians.

I’ll talk about the course structure, some of the ways I’ve designed and delivered it to meet both sets of objectives, how it has evolved over time, and what I’ve learned while giving it.

I started my career in technology, working in Customer Support for a small start up in little old New Zealand. To help our Support team scale as the business quickly grew, we needed to invest in a fool-proof self-service strategy.

We work in an industry with customers that don't identify themselves as "tech savvy", so to help them get up and running with our product quickly we needed friendly, accessible and engaging product education.

Video was one of the first things we identified as being a crucial part of our product education strategy. In this talk, I'll share my experience with using, producing and managing videos, as part of documenting an ever-changing and evolving product. We’ll chat about:

• Why you should be making videos
• When to use videos
• When you shouldn't be making videos
• How to develop a video strategy
• How to make great product tutorials

If you're looking to start your adventure in video, this talk will give you insight into how to develop and deliver a video strategy, with some helpful insights and lessons learned along the way.

As a Lean Trainer and Manager in service industries, I work with all kinds of teams to help them use process mapping to document their processes. Sifting through binders of documentation, pages of screenshots, and step‐by‐step explanations can be time consuming and awkward, and large quantities of documentation are time consuming to keep up to date. System updates would quickly render screenshots obsolete, and teams were quickly getting overwhelmed, giving up on documentation entirely. I started to apply my lean expertise to the art of process mapping, putting together a best practice toolkit to maintain a minimalist approach to documenting processes.

We'll discuss best practice in process mapping for:

• visual instruction in user guides and how‐to’s
• mapping process at high levels, avoiding getting bogged down in detail
• assessing possible failure points to anticipate customer pain points (to manage through customer documentation)

When you're suffering with an inadequate toolset, especially if you've just come back from a conference, you may feel like "Now is the time for change!". However, your first step should be analysis. Before you can decide this is the right moment for a new tool, let alone choose a tool, you need to assess your organization's needs and current status. Your decision should be defined by a triangle of factors: bigger picture strategic goals, operational reality, related processes, and existing systems. But when it isn't the right time, it is still possible to make progress with continued assessment and incremental change...

We all know what it’s like to look at a series of existing documentation and think, “how did this happen?” Be it a large swath of unorganized content or a lack of a clear strategy, the complications of bad docs aren’t just a curse for documentation editors. Our readers see it, too. It leads to confused support requests and possibly a loss of customers.

When I started at Joyent, I was continuously made aware of documentation that needed help, and it felt like a nonstop firefight. Over time, I was able to quell the fires, create a content strategy, and completely redefine how our documentation works. Then all of my work was blown up a second time ‐ this time, starting from scratch with a not yet existing product. From this experience, I’ve learned it’s all about being organized and having a clear strategy.

In this talk, we’ll discuss:

• how to get buy‐in for a documentation do‐over
• how to pivot from rewriting docs to starting from scratch
• content strategy (and how to write a great one)
• empathy for our readers
• setting easy‐to‐follow guidelines for non‐professional writers

We’ll also touch on how to prioritize and manage all of this work without additional full‐time documentation help.