Writers often forget that users are more likely to see error messages, tooltips, and helper text than to search for documentation. But these bits of microcopy are actually an opportunity to communicate and connect with users when they most need it. Most errors say that something went wrong, but the user doesn't know if it's their fault or what to do about it. As writers, designers, and developers, we need to help them fix the problem and teach them what to do next time.
Microcopy is also a chance to create a friendly relationship and establish your brand with your audience. Users are less likely to get frustrated if the error message has a personal and human sentiment than if it merely says "ACCESS DENIED", or "FORBIDDEN ACTION".
In this talk I show how making error message Humble, Human, and Helpful is critical to making your users Happy. We'll laugh at a few bad errors, and learn from the good error messages and microcopy.
You have found a secret room in the castle! You gain 26 xp.
You enter a large interior space with stone walls and a high stone ceiling. Torches flicker in wall brackets. A large self-referential tapestry hanging on the north wall shows a guild workshop full of happy weavers busily weaving the very tapestry in which they are depicted. There are exits to the east, west, and south.
Linden, another player, is here. Gwyrian, another player, is here.
> say Hi
You say “Hi”
Gwyrian says “Hey! Do you want to explore this area together?”
Linden attacks you with a critical hit from their sword!
You are dead!
Other people: sometimes difficult to work with and often impossible to predict. In your technical or documentation project, how can you get the right people interested and involved? How can you keep those people happily engaged until the work is done? Is there anything you can do to prevent griefing… err, “interpersonal difficulties” from causing delays? And why do some people seem to thrive in an environment with poor documentation and how can you encourage them to participate in effectively documenting everything anyway?
In this talk, I’ll explore ways to accomplish these aims, using strategies drawn from “Player Type Theory”. For 20 years, this theory has been employed by game designers to encourage stable long-term play communities in online multiplayer games. These are strategies that I have used successfully in my workplace and they can work for you too.
Although users typically arrive at doc websites in a confused and impatient state, not sure of where to find what they're looking for, good navigation can guide them to the right answer. Good navigation anticipates users' needs, provides links in commonly viewed places, and brings the right topic into the foreground amid hundreds of other topics.
As you build out the navigation for your doc site, follow these best practices:
Use the doc homepage as a routing portal to let users choose the right doc set. Think of the home page as a train station with various terminals for departure.
Include a navigation sidebar that contains a hierarchical representation of a group of topics. Right-size the group so that it's not too massive, nor too small, but rather provides meaningful at-a-glance context at a defined scope.
Provide breadcrumbs above your topic titles that show the path to the topics. Assume that users may not arrive at the topic in the way you expect, and they will appreciate the context that breadcrumb provides.
Provide abundant inline links in your sentences that help users navigate directly within the field of vision. Freely infuse links into phrases, words, or other parts of the sentence without always listing out the full title of the cross-reference.
At the beginning of topics, add contextual links to orient the user. At the end, add next-steps links to guide the user's next decision. For sequences or tutorials spanning multiple pages, add workflow maps to make the user's progress in the sequence clear.
We call ourselves technical writers, but many of us spend more time editing the work of others than writing ourselves. When you have a large team or a large product (or both!), the cooks in the documentation kitchen come from all parts of the company: marketing, product, engineering, sales, and more. This adds a significant burden on you and your team to make sure the content they produce is accurate, fits within your style guide, uses the correct tone, and doesn't add additional confusion.
At Mapbox, we have both a large team and a complex product, which means many different writers with individual writing styles and varying depth of knowledge of the product. To keep our work accurate and unified under a common voice while avoiding breaking our necks with editing, we implemented an automated content testing system (fully open source!) to do some of the work for us. Automated tests have helped us embed quality writing and editing into the development process as much as code testing does. "It's not finished until it's documented" is more than just a happy thought -- it's now an immovable part of our workflow.
In this talk, I will discuss the reasons you might want to implement an automated testing system in your organization, examples of how it's been beneficial, the story of how we set up our system, and a brief overview of the tools that exist for doing this work. I'll also cover the ways that automated tests can sometimes make funny mistakes and how we found the balance between making tests too precise and not precise enough. For those who are interested in implementing right away, I will also provide a comprehensive list of resources for getting started.
In this talk I'll discuss the partnership between documentarians and support and how that relationship can embolden your customers.
Documentation can make or break a support interaction. Your average customer or client isn't interested in a lot of work to use your product. They need to know how to make your product do "the thing" without, say, opening a Rails console, or doing some other godforsaken programming trick that you know.
You might not know this but your support team has a life of its own that you haven't seen. Having been a documentarian in the context of a support team, I have some pretty interesting things to talk about how you can weave relationships to make everyone's life better, all the way up the food chain.
I'll talk about how working in partnership with your support team can not only focus your docs to the points that matter, but let you see how operating as connective tissue between departments makes everyone's life easier.
00:00 Jed Hartman
06:00 Mike Jang
09:07 Joe Lodin
12:48 Paul Anzel
22:07 Troy Howard
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! You may as well die here! 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. This presentation passes along the strategies I learned so you can implement design critique guidelines into your review process and make feedback painless.
Come along on a tour of common types of documentation system administrators use to get their jobs done.
As an enterprise software developer, system administrators are my customers and colleagues. In this session, learn not just what gets used, but also what internal and informal sources to look for to create better docs. I'll share what I've learned sysadmins want from the written information they rely on daily. I'll also talk about what ops teams write for themselves that can add important details to your documents.
We’ll go beyond glossy presentation slides of instructor-led training to delve into what’s meaningful for day-to-day tasks. For example, integration and migration: to accomplish this smoothly, sysadmins need references and examples to install, configure, and customize new tools to work with existing systems. Tutorials can show how, real-world configuration examples show what, and cookbooks provide ready-made examples to customize as needed. Deployment checklists ensure the rollout goes smoothly.
Emergencies can happen at any hour—which is why runbooks can be so valuable. With step-by-step details so staff can respond without making mistakes. A junior engineer can resolve an issue without calling a developer for help. Manifests, dependency lists, and logs become necessary adjuncts to documentation, providing critical data for root cause analysis.
Learn about these sources, not just how others use them, but where you can find valuable detail to enhance the documents you write for operations.
Are you interested in developing docs like code? Are you frustrated by the lack of available information as to what that really means and how exactly you're supposed to do it? Welcome to the club!
"Treating documentation like code" is somewhat of a buzzword bingo term these days. You can find any number of blog posts, presentations, and articles online expounding on the theory and merits of the idea. When I was presented with an opportunity to truly integrate documentation into the agile development process almost 2 years ago, I couldn’t find any information that could teach me how to treat docs like code. Since then, I've worked with a team of passionate software engineers to bring a long list of 'awesome-future' ideas for treating documentation like code into practice. In this presentation, I'll lay out how we create, test, build, and publish our documentation using agile methodologies, so others starting down the same road have a path to follow.
In the beginning, we had a great idea - documentation should be developed, tested, and built just like the products we make. The keystone of this grand vision was the idea that docs live in the same repositories as the code, use the same development tools and code review processes, and follow a continuous delivery model. I'll go over the tools we chose to write, build, and test the docs; the responsibilities of the software engineers and technical writer, respectively, for creating and maintaining content; the docs information architecture we developed; how we incorporated syntax and grammar checks into code testing; and how we build and deploy our documentation automatically.
Last spring, as I approached reworking the information architecture of the NPR One Developer Center, I started by interviewing several of our partner developers to find out what pain points they encountered when developing on our platform.
Overwhelmingly, the responses included complaints about confusing site navigation and frustration around having to search multiple pages to string together the necessary information to implement features. After considering this feedback, we redesigned the documentation site to focus on information needed to complete a desired task, and while we still provide endpoint reference documentation, my focus now is to start from thinking about what a developer is trying to accomplish, rather than what data an endpoint is capable of providing. Essentially, the focus of the docs shifted away from what the API can do, towards what “I”, as the developer, can do with this API.
Taking a task-oriented approach allowed us to reorganize and revise our content in a way that has significantly shortened our onboarding process for partner developers, shortening the app verification process and time-to-market, and most importantly allows us to better collaborate with our partners to develop exciting new experiences for NPR listeners. For those who work on documenting hypermedia APIs, this can be a particularly useful approach, since these services tend to have fewer specific endpoints, and the documentation needs to focus much more on how the client can successfully navigate links to accomplish the desired task. In this 30-minute talk, I’ll discuss how you can successfully integrate this approach to your workow when considering everything from overall information architecture, to deciding which content assets to prioritize, to refining the tone used throughout your developer communications.
My name is Sam and I am the head of technical documentation department at Zodiac Interactive.
At Zodiac we create low-level software (we call it 'middleware') that runs inside cable TV set-top boxes. Most cable companies in North America use our products; most probably, your set-top box runs at least some code written by Zodiac.
Zodiac has R&D departments all over the world; my office is located in Novosibirsk, Russia – right in the center of Siberia (so yes, there is a big probability that your set-top box runs some code that was written in the midst of Siberian taiga)
Documentation department at our R&D center concentrates only on architectural documentation: our docs explain the design and architectural decisions of our software components to other teams and R&D centers all over the world . We don't document user interface, write client knowledge bases, or do UI copy. Our technical writers must be tech-savvy enough to understand the architectural peculiarities of complex multithreaded applications, must be able to read code in C++ and, above all, must have perfect written English – Zodiac is an American company, and we write all our docs in English, not Russian.
During the last 5 years our R&D center went from not having any documentarians at all to a team of 4 excellent and capable technical writers. We were able to set up effective processes of integrating documentation in overall development activities and find out good metrics for quality of architectural docs.
Documentation processes and documentation quality are frequent topics at Write the Docs, so I want to talk about more generic things: interviewing, assessing and hiring technical writers.
My talk will tackle the following questions:
How hard is it to find a "highly technical" technical writer? (remember that our documentarians must read and understand C++ code)
Is it possible to switch your non-documentarian team members to writing documentation full-time? Do developers make good technical writers? What about QA engineers? (our answer was no: it's better to hire new documentarians than to evolve existing team members into technical writers)
Which one is easier: hiring a technically capable person and teaching them to write well, or hiring a person with good writing skills but no technical knowledge whatsoever and then training them on technical stuff? (we went with the second option)
Assessing the candidates: what is the perfect pre-interview assignment test and is it OK if the typical candidate spends 10-14 days to complete it? Should your candidates write something that resembles your working docs, or some generic texts on complex topics are enough? (for example, we ask our candidates to explain SSL certificates to their math-savvy, but not-cryptographically-inclined uncle: private/public keys, digital signatures, chains of trust and so on)
Interviewing candidates for a technical writer position: are interviews necessary at all? Can a good interview outweigh a bad assignment test? Can a bad interview spoil the impression after a good assignment test? What things should be asked during an interview?
Writers of software and writers of documentation practice a shared art: we bestow abstractions with names. We know we've 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: - Why is it so hard to name things well in software? - Why do bad names persist? - What are some heuristics for assessing how good or bad a name is? - How has technology hampered efforts to name things well? - How can technology help our efforts to name things well? - How can documentarians and developers work together to name things better?
The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization by Ingrid Towey, Brice Fallon-Freeman, and Aneta Petrová
What does choosing flavors of LaCroix sparkling water for the Red Hat breakroom have to do with improving technical documentation? At Red Hat, everything.
You see, when we wanted to make a culture shift in our approach to documentation, we couldn’t legislate the change from the top down. Managers and experts just don’t have that kind of authority at Red Hat. Changing the way we write has had to be a grassroots, bottom-up effort. Just like we all get to vote on which flavors of sparkling water and other beverages are stocked in our fridge, writers, editors, content strategists, and managers ALL have a say in our latest writing trends. At Red Hat, we have an open culture where people expect to have a voice in decisions and aren’t afraid to speak their minds. This open culture affects every aspect of our working lives.
What Did We Want to Change? We wanted to introduce our teams to minimalist writing. But first we had to convince people that minimalism isn’t just about shorter sentences and less fluffy documentation. Minimalist writing means that you focus like a laser on just what your customers need at the moment. It’s harder than it sounds.
How Did We Do It? First, we formed an international team that could influence writers across all our geographical regions (geos). Brice Fallon-Freeman (from Australia), Aneta Petrová (from the Czech Republic), and I (from the US) became this team and brainstormed ways to introduce these concepts to our departments.
Aneta and Brice came up with the idea of crowdsourcing minimalist writing critiques, and all three of us tried the concept in our different geos. We got volunteers to join our groups, and then we got more volunteers who were willing to have their content critiqued. This “crowd” of writers and editors then worked together to give meaningful feedback to the people who had been brave enough to volunteer their content.
The beauty of this model is that it gives experienced writers a way to teach more junior writers without the process being apparent. No one has to admit to being ignorant. Inexperienced writers get to learn about minimalism by watching other people apply it to real content and not in some kind of fake training situation.
This talk will discuss our strategies and methods in more detail and show examples of content before and after crowdsourced minimalism.
For developers in newsrooms, whose work supports great writing and journalism all day long, writing their own docs often falls by the wayside. News deadlines can leave little time for cleanup and documentation (much less the planning that leads to reusable code). At OpenNews, these developers, designers, and data analysts are our community, and we designed a series of small events to address that time crunch. We bring people together a few times a year to refine, document, and release open-source projects, because a common set of tools means more time spent covering the news, less time on recreating code.
During these events, we've seen a common set of cultural and technical questions come up before, during, and after projects--but our community didn't have a common pool of answers.
So last year, we did something about it. Inspired by collaborative book-writing projects, we put together a community documentation sprint in December 2016. The goal: to draft a guidebook for releasing newsroom code. Over two intensive days, 11 contributors gathered with us in Washington, D.C., and another dozen signed on as remote editors. Together, they captured our community's best practices for open-sourcing software, specifically in the context of newsrooms and journalism. They worked in pairs or small groups, clustered around laptops, collaborating for long stretches of writing. We fed them many snacks.
The Field Guide to Open Source in the Newsroom launched in February, and we learned a lot as it came together. We'd love to tell you:
How we recruited and prepared a diverse, expert team of participants for a productive event
How we ran the two-day documentation sprint, with a flexible, supportive structure
How we built in time for followthrough after the event, with plans for outreach, adoption and onboarding
And how we made the whole thing human-friendly
How do you “bootstrap docs”? In this talk, I will walk through how to build essential docs for an early stage startup that lays a strong foundation for continuous improvement and expansion. The story will be told through my experiences building docs from scratch for CockroachDB (https://www.cockroachlabs.com), a next-generation open source database.
When I joined Cockroach Labs as its first technical writer, CockroachDB had been in development for nearly two years and had 15 engineers and 60+ open source developers contributing to it. I needed to build a documentation structure and process that would be lightweight enough for developers to contribute to and flexible enough to apply to the product (and team) years down the road.
This talk will walk the audience through the process of learning a new product and development team, and allowing that information to guide the information architecture and tool selection process.
Topics will include: - How do you learn a new product, and why is it essential to understand its market fit? - How do you learn about your users - who are they, what are their primary pain points, and what do they need most from docs? - How do you choose tools and workflows for building your initial docs architecture? - How do you iterate on, improve, and expand your docs, and harness contributors to do the same?
00:00 David Ryan
03:57 Ryan Macklin
06:39 John Mulhausen
11:55 Rich Marcucella
15:36 Marya Devoto
20:35 Dan Stevens
00:00 Brian Dominick
04:37 Dante Blando
09:35 Mary Ellen Niedzielski
14:47 Cynthia Ng
20:06 Ashleigh R.
24:53 Rose WIlliams & Mikey Ariel
All humans require care. Writing and maintaining documentation is a form of care: good documentation can make us feel cared-for, and we, as writers, can take satisfaction from empathizing with the end users of our work, and performing the caring work of documentation. By exploring and acknowledging the relationship between care, documentation, and technology, I argue, we can better understand and advocate for the value of our work. More so, understanding the importance of care allows us to work better.
This talk illustrates how the work of documentation is care work, and explores the ethical, philosophical and economic dimensions of care in relationship to technical writing and documentation. I’ll share findings and case studies from my own consulting practice, and explore patterns (and anti-patterns) I’ve observed around documentation and care. Then, to spur small group discussions, I’ll share design principles for documentation as care.