Documentarians and technical writers have seen many changes in our professions in recent years, and there’s no sign of change slowing down. One thing endures: the writer's goal of communicating to understanding. It’ s not as easy as it sounds. Because we are all Abbott and Costello.
Just as the first wiki changed how people write, our new wiki will change how people work. By pushing steadily on two fundamental ideas, refactoring to ease improvement and federation to ease sharing, we have once again uncovered a simpler and more powerful internet.
It's 3AM, do you know where your users are? If people want to learn how to use your product, where are they looking for help? Are they on your site, and if they're on your site, are they finding the right page?
Usability researchers have known for decades that users don't read word by word - they *scan* for the content they want.
If users can't make heads or tails of your documentation, they'll give up (a loss of revenue), remain ignorant of product features (another loss of revenue) or ask needless support questions (an increased cost).
In this talk we'll examine the *findability* of your documentation, and the text on the pages in your documentation. We'll examine usability research into how users read, look at several ways your documentation is failing busy users, and the lessons I learned conducting user tests at Twilio. We'll learn more about how users find the answers they are looking for, and the importance of spreading clear writing across not just your documentation, but your headlines and error messages in your API.
Last year, we were inspired to action by a presentation at Write the Docs. This talk will tell the story of what happened next: how, in two quarters, we worked with a small self-forming team of amazing writers and engineers to build a platform in six months is well on the way to becoming a part of the standard Google engineering workflow. We’ll share how that platform transformed our role as technical writers and our relationship with engineering. We’ ll cover design and implementation details, but we’ll also talk about our experience - how we learned that being audacious (but not reckless), focused (but open and generous), and unafraid could revitalize our whole approach to work and save us from burnout.
We'll talk about our ever-growing appetite for disruption: How it changed beyond recognition our relationships with engineers, fellow writers, and senior leadership, making us fall in love again with our roles as documentarians.
"People who hope to thrive in the Conceptual Age must understand the connections between diverse, and seemingly separate, disciplines." So says Daniel Pink in his book, A Whole New Mind: Why Right-Brainers Will Rule the Future. In this talk, I assert that tech writers are a natural fit to help their organizations transition from the Information Age to the Conceptual Age. I'll also give and seek ideas on how we as writers can apply Pink's six aptitudes -- storytelling, empathy, design, humor, games, and finding meaning -- to make our work more fulfilling, if not more competitive.
The key underlying message for those who attend this talk is: YOU are a designer. Even if you haven't traditionally seen yourself in this role, writers are information designers who serve a unique, user-focused and holistic function on development teams. By recognizing that fact, and opening up space in your work life for creativity, you can have an even bigger impact and a more fulfilling career.
How did Mozilla Developer Network (MDN) achieve a 46% increase in active editors and a 90% increase in translation contributions in 2014? Many factors helped, but a major element was the support we added for new contributors.
“Scratch your own itch” is the proverbial invitation to contribute to open source projects. How well this works for contributing to code is open to debate, but it rarely makes sense for open source documentation, especially for well-established projects. Not only is it unhelpful for the project, which typically has plans (or at least wishlists) for improving the docs, but it provides very little guidance to the contributor as to what they might do, what they personally are able to do, and what would be most helpful to do.
In the 10 years that MDN has been a wiki (some of the content pre-dates the wiki), the community has always welcomed constructive contributions by anyone who bothers to create a user account. Over the years, we’ve created meta-documentation about contributing to the site, including wishlists of things we’d like to see documented. However, these didn’t necessarily help newcomers gain traction.
Only in the last year or so have we created documentation to help new contributors specifically. Our aim is to help newcomers find the right match among:
I’ll describe the features we’ve put in place to achieve this, as well as things we’re still working on. I’ll leave space for discussion so we can all share ideas and successes.
We talk a lot about minimum viable products, and building our products up from small features. We talk a lot about failure, and how to learn from it and not replicate failures over and over again. But what I haven’t heard a lot of discussion about is how we know we’ve succeeded. Is it market share? Usable product? Could understanding and setting a measurable, achievable goals help us overcome imposter syndrome, second sock syndrome, and feature creep?
This talk provides some metrics on identifying success, documenting what it will look like when you get there, preserving the idea, and dealing with the inevitable distractions and changes in direction that may prevent you from ending up where you expect.
I plan to speak on how documentation can serve a crucial function at both defining and driving success. We need to stop believing that agile is the end of the answer and embrace it as part of building what we want to have in the end.
Continuous improvement can have a victory condition, if we build it.
The era of O’Reilly books is done, finito, kaput. With so much of the developer experience online, we know a great deal about each individual user and about the code we document. Why, then, do we documentarians persist in providing the same walls of text to each of our readers, especially when there are so many more personalized ways of describing technical tools and code?
This talk addresses the move from passive to dynamic documentation. As code goes mainstream, more and more consumers of APIs and technical writing will be non-technical. Technical writing bears a responsibility to reduce the learning curve as much as possible for these readers, and it can do that by being much more intimate about its relationship with them.
Everyone knows that GitHub is the place to host your project's code. What you may not know is that the same workflow developers use to create, update, and manage their software is also used to create, update, and manage GitHub's documentation.
https://help.github.com is GitHub's second-most viewed site--after the main website itself. I'd like to provide a somewhat opinionated look on how our valiant Documentation team writes and releases content for features on GitHub.com and GitHub Enterprise. I'll go over:
As documentarians, we are rarely afforded an opportunity to thrive in a pristine greenfield environment. Sometimes we are asked to resurrect an existing documentation system which had fallen into a derelict state over many years. To turn this ship around, we must shepherd contents, customer base, and internal Subject Matter Experts into a future state where outdated, neglected, and ambiguous support documents are transformed into timely, relevant, and pleasing works of art.
The role of the documentarian is to help execute this transformation. However, we are often asked (or voluntold) by our organizations to wear other hats beyond our primary writing duties: repair and build relationships, analyze business processes, learn about how others react to change, discover unknown troves of documentation, train and encourage the next generation of writers, gather and crunch data, tell stories, design workflows, and perform “other duties as needed.” Some may respond with an exasperated “I wasn’ t trained on this!!!” or “That’s not part of my job!” But those of us who embrace the opportunity to stretch beyond our areas of expertise and learn new peripheral skills may realize that working on a documentation equivalent of a cleaning up Superfund site can turn into super fun.
In this talk, I will share my experiences and lessons learned as a technical writer who is witnessing this documentation culture change, one conversation at a time. Wearing many hats can be exhilarating and rewarding.
A software tester can be a tech writer’s best friend, and vice versa. Jody (writer) and Arthur (tester) work together on APIs at Salesforce.com, and we’ll talk about the tools and techniques we use to improve the quality of both our software and our documentation at the same time.
While our APIs are still in development, we gather feedback internally. We established an API design review board to approve every API change -- this made a huge difference in ensuring that we offer a consistent, easy-to-consume programmatic interface to our users. We also conduct regular “dogfooding” sessions in which users are provided with draft documentation and asked to find both doc and product bugs.
Our testers created an automated mechanism to alert us of any API changes in case anything slipped past the review board. It’s proven to be invaluable for both doc and testing to keep up with the various teams who are building functionality into the API.
Once our APIs are publicly available, we take pride in listening to our users in help forums, on Twitter, and through pilot programs. We’ve clarified our documentation and added test cases numerous times based on customer pain points.
When people have to stop to understand labels and instructions, they can't stay engaged in their experiences. My job shipping Xbox One was to use words so well, people wouldn't notice them at all. In this talk, I'll show the only 3 reasons I use words in user interfaces, how I find the right words, and how I increase engagement by respecting people’ intent.
To new users, complex software products can seem like dark woods on a stormy day. As tech writers, we often spend a lot of time talking about the overall shape of the forest and the variety of paths within it (conceptual docs), creating detailed catalogs of local tree species (reference docs), and providing step-by-step guides to things like “how to cross a river” or “how to knock on a door” (task-based docs).
But none of that helps your customers when they just want to know how to get to Grandmother’ s house, without getting lost in the forest, falling into the river, and accidentally going to the other cabin in the woods, where the lycanthropic senior citizens live.
In other words, your customers need a narrative. And maybe they need lots of them. When you’re dealing with products that can be run and configured in a bewildering variety of ways, a single getting started manual might not do the trick. It’s like giving people a Choose Your Own Adventure book and only allowing them to choose one path through to the end.
For my talk I’ll explain how we became aware of the need for better scenario-based documentation, and how we ended up building a prototype during a hack week project. Now we’re on our way to creating a collection of short stories that show users how to string sets of features and procedures together to solve complex problems. We’ll cover some of the things we’ve learned along the way and offer best practices for those who want to tell a few stories of their own.
Matt Ness is a technical writer with over twenty years of experience at places like PeopleSoft, Oracle, and Intuit. He's currently a writer for Splunk, a leader in the machine data analytics sector.
Every tech company or organization organically produces docs in some form, but as scale increases, the information design decisions you started with will almost certainly serve some information consumers better than others. Depending on who's creating information and who's using it, the approach to designing and delivering information can be dramatically different, with very different outcomes that probably won't work across an entire larger organization. Be aware of the information design decisions you're making so you can plan for growth. Design by default is not a good strategy!
This talk discusses how:
A mathematical proof is a logically rigorous way of showing that something is true. It begins with a statement of the desired result and any assumptions that must be made. It guides the reader through a set of logical sequential steps, supported by figures to aid intuition or cross-references for prerequisite knowledge. It ends by declaring that the desired result has been achieved. At risk of insulting every mathematician who ever lived, in many ways a proof is not so different from a grand, abstract how-to document.
Perhaps surprisingly, for most of human history mathematical proofs and mathematics itself have been written in prose. Even those of us who cringe at the memory of high school algebra can agree that “10x + y^2 = 3” is more user-friendly than “the sum of an unknown quality multiplied by ten and another unknown quantity multiplied by itself is equal to three”. The first part of this talk explores the development of mathematical writing, which can be divided into improvements in symbolic representation and improvements in structure. This discussion is partly inspired by Bret Victor’s observation that the most influential breakthroughs in the history of mathematics were actually breakthroughs in “UI design”, for example the invention of Arabic numerals (0, 1, 2, 3,...) as a replacement for clunky Roman numerals (I, II, III, IV…).
Proofs and rigorous documentation empower their readers to greater understanding by never relying on authority or persuasion. A mathematical proof, unlike a scientific experiment or a souffle recipe, must show that the desired result is *always* achieved when the right steps are executed under the right conditions. Users of computer applications certainly expect documentation to live up to the same standards. The second part of this talk explores the concept of mathematical proof in more depth. We will look at how proofs are structured and use logic in a particular way to minimize ambiguity and maximize credibility, and how the writing process is itself a powerful tool to root out hidden assumptions and errors in thinking.
Here at Atlassian, we’ve been moving ever closer to a world of continuous deployment for our software products. Five years ago, releases took months. Now, many products are releasing every two weeks at a minimum. In addition, the past year has seen features being deployed as soon as they pass testing. What’s a tech writer to do!?
In true agile fashion, the response to these challenges varies across products and writers within Atlassian. This gives us a breadth of stories and examples I can share about our experiences in this world. Here’s a high-level look at what I’ll share:
With just a little work, you can feel the joy of Write the Docs all year!
I started the Write the Docs PDX Meetup Group back in May of 2014, just after last year’s conference. As the only writer in my office, I often feel alone. At Write the Docs NA 2014 conference, I felt the joy of interacting with documentarians like myself, people who were facing similar challenges. I wanted to continue feeling that joy.
I’ll describe my experiences creating a Write the Docs Meetup group in Portland. I’ll show you how easy* it is to create a Meetup group, attract members, get sponsors, find speakers, and make sure all members of your group feel welcome. I’ll tell you about the Meetups we’ve had, and what we learned from each other.
More importantly, I’ll lay out the ways you can continue the conversation we've had during WTD 2015. I'll share my best practices for excellent Meetups for Documentarians.
*Yes, “easy” is a euphemism for a lot of hard work. But the people you'll meet and the contacts that you'll make can reward you and your company in other ways.
At OutSystems we make an awesome development platform, but our documentation wasn't that awesome. We focused on describing each button available on the user interface, and not the user intentions and goals.
A clear example of this, was that we had a full documentation page for the find text feature (CTRL+F). It described in excruciating detail every option available on the UI, but didn't told our users how they could actually find what they needed!
For us it was a nightmare to maintain the docs. Our development environment was constantly changing and we couldn't keep up with the changes.
More importantly, we weren't meeting the user needs. And that was clear from pages with a single-digit page view, and from the feedback we got from our customers.
Due to this approach, we also ended up having page titles that were feature-oriented, which is not the best for SEO. For instance, the doc page for the find text feature was called "Find Tool". Who in their right mind would search for that on Google?
In this talk I'll tell you the story of how we stopped trying to document the UI, and started creating user-story driven docs. We now focus on what the user wants to achieve and how to achieve it, independently of how many windows or buttons they need to go through.
At Fastly, a San Francisco-based content delivery network startup company, I’ve learned that almost every one of my co-workers, regardless of their job function, is willing to write our company’s documentation. Whether they realize it or not, each one of them has ventured onto the path of becoming a “writing team black belt.”
In this talk I’ ll discuss how my company has unwittingly followed the seven (and a half) rules I normally associate with becoming a great martial artist. I’ll discuss how we’ve been using these rules to forge an amazing ad-hoc documentation team with no formal department and no squad of strategically placed technical writers. I’ll talk about how my company has managed it despite the obstacles of startup life, including moving seven times and growing from less than 30 employees when I first joined to a throng of more than 150 a mere year and a half later. Finally, I’ll point out some of our successes, a few of our failures, and how each of the seven (and a half) rules has taught us what it means to write Fastly.
Companies spend big bucks developing content to attract and retain customers—most of it, forgettable. In fact, according to some cognitive scientists, people remember only 10 percent of what you say. The other 90 percent is forgotten. To make matters worse, the 10 percent that people remember differs between members of your audience.
Imagine the time and money we could all save if we knew how to control what our audiences remember about our content, if we could break through all of the distractions with content so compelling that our audiences couldn’t ignore our message.
In a blog that I wrote, I had the opportunity to interview Dr. Carmen Simon. A co-founder of Rexi Media, Dr. Simon holds doctorates in instructional technology and cognitive psychology. We explored how science could help us design memorable content.
In my Write the Docs presentation, I’ll share five scientifically-based techniques that the audience can apply to their own content and presentations to make them more memorable and influential. This presentation will be based on information from my interview with Dr. Simon and other sources.