Before becoming a full-time software developer, I spent more than twenty years working on dictionaries and other reference books. Reference books and dictionaries have a lot of similarities with documentation: they're both genres of writing that aim to explain and educate, and are aimed at an audience that is largely goal-oriented and impatient. In this talk, I'll give a little bit of background on how reference books (particularly dictionaries and thesauruses) are made, talk about my experience in publishing has informed writing documentation and tutorials (and working with Swagger/OpenAPI), and give some examples of habits I had to un-learn, too!

Ah, good old FAQs: the internet’s native documentation format. In this talk, we’ll explore various questions we might frequently ask ourselves about FAQs, such as:

• Why do readers always seem to want them even though they’re routinely out of date?
• Why do some readers ignore our carefully crafted pages and use these giant walls of text as a starting point instead?
• What are some strategies for keeping FAQs up to date?
• What’s the #1 thing FAQs do RIGHT?
• How can we make FAQs more user-friendly?
• Do we even actually need FAQs?

(Caution: May contain opinions.)

Our team has the classic documentation problem--a huge backlog of work and not enough writers. Enter the documentation internship program, which connected us with junior and aspiring technical writers and got us headcount fast.

This talk will teach you how we recruited, interviewed, and hired inexperienced writers, and taught them the basics of technical writing… all without damaging our velocity.

I’ll focus specifically on how our job pitch got us applicants from a wide array of backgrounds, from screenwriters to college students, how we made sense of the answers we got through an unpredictable set of interviews, and how we onboarded writers with strong skills and aptitude, but no real-world experience.

API documentation can been grouped into four classes—Overviews, Tutorials, How-to topics, and References. Each addresses a different customer need and each requires different amounts of time and types of resources to produce. However, what happens on that fateful day you find that you have more documentation to write than time will allow? (As a technical writer, I call those weekdays). How can you prioritize which documentation type and how much of it should be written and which topics to write first?

This talk provides guidance and encouragement to technical writers to help them get the information they need to strategically get the right docs to the right people at the right time—and learn a little bit more about their stakeholders along the way.

These core principles have guided me during my (almost) two decades in the business. I'll share some real-world stories to show what kind of results you can expect.

The tips:

• Just ask.
• Listen for intent.
• Create the minimum thing.
• Cultivate ownership, individual and product.
• Be a lifelong learner.
• Opt in.
• Use the power of storytelling.

There might even be a surprise bonus tip.

Thorough and optimal technical documentation often requires not just an API reference of endpoints and parameters, or long contextual instructions, but also code examples that users can cut and paste into their applications. As a technical writer at Stripe, I’m partially responsible for maintaining 150 code examples, each of which needs to be in 8 programming languages. In this presentation, I’ll explain the processes we’re using, the hurdles we’re facing, and the solutions we’ve devised thus far to make and maintain code examples that really shine.

Specific concepts covered include:

• Defining a style guide for your code
• Generating code examples programmatically
• Testing examples to ensure they work
• Using common snippets to save time
• Enhancing examples for a better user experience

Although we haven’t solved all our problems in this area, we’ve made great progress with great results, and I look forward to sharing our best policies and practices.

I’d like to talk about the role of an editor and the art of enabling humans to create, publish and present technical content in a variety of media. Primarily in text, in the context of a blog or other ‘managed’ calendar-driven web publications. Not technical documentation. Sometimes it’s a mighty fine line between docs and blogs, but I think we can and should differentiate.

This talk will explore principles and patterns of kind, effective editorial practice, and nuances of voice, civility, and clear communication, as they play out when working with a diverse distributed roster of authors, many of whom are non-native English speakers or first-time storytellers.

I believe there’s as much appetite for diversity of voice and point of view in blogging about software development as there is in speaking about it at developer conferences. And I’ve got some observations to share about how we can cultivate that.

In the wider tech writer world, it’s still common to hear tech writers be certain that developers can’t write good help: the prevailing sense is “Only we can do this.” But those same tech writers often feel under threat in their jobs - feeling like their organisation doesn’t see their value, doesn’t understand what they do.

Who should write the docs? Should all developers write docs as a matter of course? Is it even worthwhile having specialist writers?

In this talk I’ll try to find some answers to these questions, based on my experience working in many teams - both in teams that have valued tech writing and in teams that haven’t. I’ll talk about the ‘documentarian’ mindset and how that contributes to better software, no matter what your job title is.

I’ll also explore the benefits that come from specialist writers and generalist developers working together. And I’ll share the ways I’ve found that people with specialist writer skills (whether they’re developers, tech writers, or other roles) can make the biggest difference to user experience, and through that to their organisations.

In a tech writer’s career, creating and maintaining a great portfolio is as important as it is stressful. What belongs in there? What constitutes your "best work"? What if all your work is proprietary? Do you really need a portfolio if you have a great job?

Building a portfolio is an exercise in documenting yourself: your writing, your skill, your journey as a professional. Like any other kind of documentation, it isn't easy or intuitive to create something great. And like any other kind of documentation, it's worth doing the hard work to get it right.

In this talk, I cover:

• Why you need a portfolio even if you have a stable job
• How to create a well-rounded portfolio and decide what's your best work
• Strategies for adding proprietary work (legally!)
• Options to present it that aren't just a series of email attachments

Congratulations! Someone realizes your awesome product needs equally awesome documentation, and you’ve earned the job! It’s an exciting new role, with new goals and challenges.

Cue the panic: There are too many things to do! Where do I start? How can I succeed in this role?

I’ve been there before. In fact, I’ve done it multiple times. Like medical triage, you won’t have a lot of time to think before you dive in and get to work. It’s stressful, even if there are no lives at stake!

But you can be fast and smart. I’ll tell you how to get started (audit the existing content, create a list of requirements for documentation tools, ruthlessly prioritize a huge list of tasks) and how to keep going (build relationships with coworkers in customer-facing roles to learn what your customers really need from docs, take a moment to pat yourself on the back every now and then). I’ll also admit to mistakes I’ve made, and how I’ve learned to avoid them (like trying to do everything myself, or thinking that time spent planning is taking away from “real work”).

Your new role will require hard work, but a bit of advice can help you get started, stay motivated, and avoid pitfalls along the way.

Ever lie awake at night wondering, How do we know if our documentation is any good? What does “good” mean, anyway? Well, you’re not alone - but the good news is, there’s a way to find out! The secret lies in caring about your developers and actively working to learn how your docs serve them (or don’t!)

In this talk, I’ll share the story of Twilio’s journey toward empathy-driven documentation. By leveraging direct user feedback, user experience research, and constantly testing the effectiveness of the docs you provide, you can learn how your users work with (and wish they could work with) your docs.

Along the way I’ll share a few tips about what worked well for us, what ideas didn’t pan out, and some of the documentation principles we’re now sold on.

Style guides are a key tool for many documentarians — they guarantee consistency, streamline onboarding, and even improve the documentation non-technical writers create.

Whether you're creating an internal style guide or a commercially available reference, though, there are plenty of pitfalls. In this talk, we'll cover:

• style guide assumptions (and how to avoid them)
• jargon, slang, idioms, and other words with multiple meanings
• inclusion, sensitivity readings, and generally making sure you know how other people hear terms
• teaching style across a team

We all want to create docs that help our users. We know good research helps us to give our readers what they need and poor research can weaken our docs so it’s time to step up our research game.

Grounded in the things I’ve learnt (read: mistakes I’ve made) from my time writing open source documentation for the UK government at Government Digital Service (GDS), this talk will look at:

• deciding what - and how - to research
• interviewing, simulation and content evaluation techniques
• distinguishing user ‘needs’ from ‘wants’
• how the Hawthorne effect can influence research
• how to feed findings into product and content development

Throughout it all, we’ll cover strategies to avoid common pitfalls, how to avoid users telling you what you want to hear, how to manage research with no extra budget and, when it’s all done, how to turn all that qualitative data into tangible content changes that have a genuine impact for users.

There are multiple reasons to use screenshots, from introducing new features and helping confirm the context of content to simply breaking up walls of text. However, screenshots can carry a lot of overhead, including localization considerations and short shelf-lives due to continuous deployment, which may make them more effort than their worth. For content that appears in context of the UI, screenshots can also be redundant and unnecessary. As alternatives to screenshots, there are several visual content strategies to consider to engage audiences and convey and complement concepts and UIisms, including infographics, illustrations, and abstract "simplified UI (SUI)" representations. Which you use depends on your intent and message.

Years of being one of the "technical people" in activist circles resulted in my being continually called on to help community groups and fellow organizers understand and more correctly wield technology in service of their mission. Using my blogpost "Three Tips for Providing Tech Help to Non-Profits and Other Such Organizations" as a point of departure, I will share my experience and derived best practices.

From "basics", like how to use documents and spreadsheets, to working with databases and understanding security, I have given assistance to a great many groups and the most important part is always the documentation that I leave behind. I can rarely ever just point people to the official software or open source project documentation, I almost always have to rewrite the docs for them in simple language that references their specific use case.

I wish to help community and activist groups make better technical choices so that they feel more in control of the technologies they use. My hope is that in sharing my experiences, I can engage in a deeper dialogue with the technical documentation community about how we can make technical documentation more accessible, easier to reuse, and empowering.

You have an idea for the next great technical book. Maybe you're excited about a new technology that nobody's written about yet. Maybe you're unimpressed with the books that are out there on your favorite topic. Maybe writing a book is on your bucket list. This session will help your idea reach its potential as a published book. Technical publishing is an opaque process with a lot of moving parts, which can be confusing for outsiders to navigate. This session will guide you through the steps you should take to turn an idea into a proposal that a publisher will accept, and what to expect from the publishing experience.

Creating a great technical book takes more than a good idea. It also requires a knowledge of the market, to determine whether there's an audience willing to buy, or whether the space is too crowded to accept new entries. Publishers vary in their approach and target markets, so you need to determine which one will provide the best chance of success. Self-publishing is an option, but carries its own risks and benefits. Doing the setup work that you may not have thought about yet will help you create a proposal that will appeal to publishers, and will also make the writing process easier.

Once you have a contract with a publisher, or have decided to self-publish, it's more than just a matter of putting the words in order. Finding the right environment, setting a schedule, and communicating with your editor are all critical to success. This session will explain how the process works, highlight the parts you may not know, and give you advice on how not to get overwhelmed by your project.