We had a number of interesting presentations about companies transforming their documentation process. Instead of choosing just one, we asked the speakers to join us on a panel, so that folks can compare and contrast the different approaches.
What if U.S. federal agencies decided to reuse and contribute to open source software projects built by other agencies, since agencies often have similar technology problems to solve? And what if they hired technical writers with open source community experience to write documentation for these projects? That would be pretty cool. Also, that’s my work. I'm part of 18F, a digital services consulting team within and for the federal government, and all of our work is open source.
I’ll explain surprising and rewarding aspects of working on documentation in government, through the lens of the cross-agency eRegulations project I’ve been working on. The Consumer Financial Protection Bureau started it, our 18F team (in the General Services Administration) adapted it for the Bureau of Alcohol, Tobacco, Firearms, and Explosives, and we’re adapting it for use by two more agencies.
I believe open source software development with good documentation aligns with core values of our government: work by the government belongs to the people, so it should be as transparent as possible, open to input from the people, and reusable by the people. The implementation of those values is the complicated part, of course! I’ll explain how we get stuff done at both the big-picture level (how laws and government economics shape our work) and the day-to-day details (how we work across teams to get useful information online).
Come with me on a journey and learn how Atlassian went from the traditional "Technical Writing" team, to the Information Experience team. What began as a simple challenge to the Atlassian Technical Writing team, to make quality and success measurable and repeatable, grew into a journey to create a "cradle to grave" Information Experience. And we're just getting started. During the last two Write the Docs I've given a lightning talk, Write Measure Repeat, which covers one very small part of the change we've undergone. This year I'd like to tell the rest of a story, which is some of the most exciting work I've done in my career. I'll talk about the process of creating and growing a writing culture which is technically accurate, writes with a human voice, and connects to every other part of the information experience. While talking everyone through the journey I'll be sure to cover specific examples of using content strategy, user research, data analytics and a touch of team process. All this with a bit of humor and a passion which is obvious to anyone who's ever met me.
Main points I'll touch on:
User assistance (documentation) is basically self-service customer support. Both documentation and customer support are critical to the success of any company, and they work better when they assist and improve each other. How can tap the knowledge of our support agents to improve the documentation, and how can we make the lives of support agents easier in return?
I’ ve worked very closely with customer support and customer success teams for years, and I’ve gone from thinking of them as “the RTFM, turn if off an on again folks” to being their biggest advocate and fan.
Let me tell you how documentarians can work with customer support to turn the F in RTFM from F*** to FANTASTIC!
How does a documentarian work with customer support?
As technical writers, it’s easy to sacrifice human connection in the strenuous effort to present technically accurate information. Maybe you feel the human connection is marketing’s job, or if you’re in a highly technical field, maybe you think your users are smart enough to make the connections themselves. Maybe you have so much work, it’s all you can do to write something technically accurate before moving on to the next update. The result can be documentation that is airless, academic, and overly technical. In other words, not something that users would want to read! If the success of your company depends on your users actually using your documentation, you have to engage them and build understanding.
This presentation will discuss how to create documentation that engages readers and focuses them on what matters. Using the writing process developed by Peter Elbow, author of “Writing without Teachers,” I’ll show how to conduct peer reviews that elicit the reader’s subjective experience -- what Peter Elbow called “movies of the reader’s mind” -- to reveal the ambiguities that can plague our writing. We’ll look at how to use the "summary and sayback" and “ center of gravity” techniques to help writers distill a technical passage down to its core. We’ll also look at how giving your documentation a more human voice can improve not only the reader’s experience, but your own experience as a writer as well!
Your new engineer started on Tuesday; your internal docs should ramp them up. Your founding engineer's last day was yesterday; your internal docs keep their projects from falling through the cracks. Tomorrow you'll switch to a project that's already in progress; internal docs should help you catch up.
Too bad your internal docs are haphazard, out of date, and mostly nonexistent. Welcome to startup life, where speed is prized above almost all.
At startups and other fast-moving organizations, the imperative to ship provides a convenient excuse to skip writing the README.md. But should we accept this as the cost of moving fast? Or can we reframe how we communicate the value of documentation so that the message resonates in startupland? Can we adapt how we practice the art of documentation so that it happens even when nobody has time?
I'd like to share my successes, failures, and hard-won lessons as an engineering lead and manager who has pushed to bring writing documentation into the internal culture and practices of a startup's engineering organization.
In 2014, as the new documentation coordinator my challenges were: 1. Create a living knowledge base that people want to use 2. Switch from just-in-case documentation to just-in-time documentation
In order to start churning out content, I designed a workflow process called Just- In-Time (JIT) documentation. Just In Time is actually a production strategy that is used primarily in manufacturing, to cost-effectively manage inventory supply. Some say that the approach originated in Japan, others credit Henry Ford. As we applied it to documentation, just-in-time means that we create the just enough documentation, just in time. This presentation covers how we created this process, how we’ve refined it and its success.
Not so long ago, designers were not part of the product development cycle. They were only called at the last minute, with the hopes they could help salvage the project. But by then they couldn't do much, since it's hard to backtrack from bad design decisions made early on.
Fortunately this has changed. Both management and developers now see the value of including designers as part of the development cycle.
The same has to happen with tech writers!
In this talk I'll share with you the 7 core values my tech writing team used at OutSystems, where we changed the company culture and won our place in the development cycle.
These values are also being useful to me at Docker, where I'm still learning about the product, the users, and the best way to ship documentation.
I'm Sharon, Editorial Manager at DigitalOcean. I'd like to talk about what my team does every day: publish technical content from the wild. We publish content from subject matter experts who not only aren't professional documentarians, but who don't even work for the company.
I'll go over how we solicit submissions, how we select content and authors, how we reject unsuitable applications, how we test and edit the work, and how we build relationships with community writers.
I'll also contextualize how this works well in the realm of open-source software, and what to consider if you adapt this model for your community.
A README file often makes your software’s first impression. In this talk, you’ll learn to put together a README that makes a great impression, even if you have little time or writing skills.
At the top of your directory tree, your README is your software’s resume: it’s often the first and—if you’re not careful—the last thing anyone sees of your software. But you may not have time to craft a bespoke README. That’s OK! In this talk, you’ll learn:
From your project’s name to what’s in that LICENSE file, you’ ll learn what to write first and what mistakes to avoid, so that your README wows new users, helps colleagues or contributors, and maybe even does your future self a favor.
Like Mike Jang’s Ignite OSCON 2015 talk “Ten Steps to a Better README”1, this talk will recommend style and content, but with a greater focus on the process of writing a README. While inspired by open-source approaches to READMEs—including readings of style guides such as 18F’s “Making READMEs Readable”2 and the READMEs of all projects that have 10,000 or more stars on GitHub— this talk will not be limited to the context of open source.
Whether you're new to the genre or a README connoisseur, you'll learn a process to write a README that works for you and your audience.
Distributing example code and applications with documentation is now easy. There are a million different ways to get code to people: from zips, to GitHub, to gists, and beyond. Code is easy to distribute. But how do we create a better link between example code, and written documentation?
Luckily, clever boffins have come up with some solutions: interactive document environments. These let the live code and the documentation sit side-by-side with one another, the distributed example code is the documentation.
This talk will take a brief look at some of the different interactive document environments out there – mainly IPython Notebooks and Swift Playgrounds – and the various strengths, weaknesses, and caveats of these tools. We’ll also explore the future, and discuss where these tools are going, as well as the implications for technical documentation.
You’re smart, educated, and you’ve been working in this industry for years. You’ve created amazing open-source packages and great documentation. But all that flies out the window if what you write about your project isn’t being read.
“But it’s comprehensive! It has all the info that I would need!” you may reply.
The problem is not writing for people like you; it’s writing and creating documentation that anyone can read, understand, and get excited about. This is true for projects aimed at beginners, but it goes double for projects and writing aimed at intermediate/expert programmers. Your projects will benefit when you write something that everyone can understand and would want to read. More readers = more users = perhaps more contributors!
In this talk, I’ll discuss my adventures learning to write effective product copy for web and mobile apps. I’m a passionate believer that app copy is a magical panacea for bad user experience. When presented effectively, good copy decreases nearly every problem your users face, including frustration, ignorance, and workflow obstruction.
I’ll cover the following points in more detail:
App copy is documentation for people who don’t know your knowledge base exists.
Open source projects have documentation communities made up of volunteer enthusiasts and people from different companies. Good open source documentation is essential to the success of a project, and working within an open source community is entirely unlike working inside a single company.
At Red Hat, our products are based on dozens of open source projects and built on the hard work of hundreds more. Our documentation has to serve the needs of our customers and add value to our products. At the same time, we need our upstream projects to be healthy and vibrant, and that includes having excellent documentation and documentation communities.
Shaun McCance will talk about how to balance upstream and downstream documentation and how multiple teams can work together to create better documentation for everyone. He'll show examples from inside Red Hat, as well as from over a decade in working with open source documentation communities.
Writing fiction and writing documentation have much more in common that typing out large blocks of text. This talk will talk about elements of fiction writing that improve the process of writing docs: Understanding audience: the tools fiction writers use to understand their audience (as well as to communicate with them) offer deeper looks at who reads what. The process of connecting with an audience is integral to fiction, but often overlooked in documentation — resulting in hard-to-use docs that don’t help users. Building story arcs: arguably, all fiction boils down to about seven different plots, retold in millions of different ways. Understanding underlying story structure makes the process of writing new tales much easier. Those story structures and plot elements can map directly to parts of documentation, as well as show options for creating standing elements for documentation. * Writing prose worth reading: documentation can be enjoyable to read, provided a writer is willing to invest time in crafting good reading material.
This talk will draw on examples from both popular fiction and documentation out in the world today.
As a tech writer, you care about two things: knowing your audience and delivering the most concise information possible to that audience. But how do you do that when your audience is incredibly specialized? What if the information you’re presenting is rapidly changing? How can you be certain that your documentation is always relevant for that audience?
To answer all those questions, at New Relic we use CSAT (Customer Satisfaction) data. Our Docs team monitors CSAT comments and data for every single public-facing doc we own. We use that data to make dynamic decisions that affect our site and our docs work, influencing everything from quick doc fixes, giant rewrites, and our own site’ s functionality.
Every pertinent comment receives attention from at least one tech writer. Part of our code example is out of date? Fixed. There’ s a glitch on our site? We’ll look into it. We list a version of Mongo that’ s outdated? Updated. By focusing on these comments, your audience is working with you to keep your documentation updated.
What happens when a customer doesn’t leave a comment, and just says the document wasn’t helpful? We track that too. When docs have consistently negative feedback without constructive comments, we know that at least something in that doc needs work. When that happens, we work with SMEs to rewrite those docs and give them a little love. We polish ‘em up and publish them again, tracking their data afterwards to make sure that they’re indeed improved.
And this doesn’ t just benefit the Docs team. We’ve forwarded UI complaints to design, and disgruntled customer comments to Support. That’s part of the beauty of CSAT: it’s a direct line to all the customers looking for help with our products. With CSAT, our audience is helping us to curate the best possible information for all their needs.
But we’re not stopping there. Soon, we’ll be implementing OAuth for our CSAT data. Once that’s enabled, we’ll be able to see what specific products customers are using, what region they’re in, what type of user permissions they have, and a ton of other stuff. We’ll be positively swimming in audience connectedness from our CSAT, and with it, we’ll know that our audience is understanding our concise information in the best way possible.
Documenting an API can be an intimidating process: How should you organize the documentation? How should you present the endpoint reference? What sorts of conceptual information are developers be looking for? Where to start?
This talk provides the answers to these questions! We’ll go through organizational strategies for API docs and discuss ways to handle the reference, tutorial, and conceptual material you might need to produce. Throughout, we’ll focus on thinking about what the end users need and building the docs to support those goals. We’ll also look at modern tools that can make your API documentation useful, usable, and snazzy-looking, and talk about strategies for documenting APIs when you’re stuck with a publishing tool that might not be ideal for the task (Madcap Flare, for example).
In order to be an effective technical writer, you must carry an entire cast of characters in your head. So many, in fact, that you might feel like you need help from a great and powerful wizard just to keep up. You already have a Brain, full of technical knowledge and communication skills. You already have a Heart, open to forging alliances with your co-workers, teammates, and SMEs. If you only had the Nerve, so that you could carve out just the right place for you and your documentation and become the king of the how-to jungle.
From a new(er) writer to new (and experienced) writers, this presentation offers strategies for fostering courage in technical documentation. I will share the methods that fortified me while working on my first tech docs, some game plans for staying bold that I used as I gained more experience, and the secret I discovered about cultivating courage no matter where you are in your tech writing career.
The hectic pace of documentarian tasks is only accelerating these days, spurred on by things like continuous deployment and tools that enable a new, higher level of collaboration. These changes bring not only unprecedented opportunities but also unprecedented challenges.
Today's technical communicators need to adapt to cope with this change. In this talk, Tina the Tech Writer is back, now leading a team of writers. The team has been almost too successful at proving the value of documentation. Facing a mountain of urgent requests for documentation coverage, potential writer burnout, and attrition, she puts her hedgehog brain skills to practical application on a plan to bring the team to new levels of engagement, happiness, and value -- all while learning to say no when appropriate. It's all about balance. Tina will share results from her team's experiment, while outlining a way you can design your own plan to balance any set of challenges and opportunities you're facing.
Documentation for most web applications today still follows the cognitive model of the good old fashioned documentation manual: While there might be some help content in the UI, the actual documentation manual in most cases lives as a separate object that is except for a few deep links on particularly troublesome areas, only accessible through a top domain.
But it doesn’t have to be this way, we should be perfectly able to predict what help resources a particular type of user might need on a given page, or functional state of a web application. Why do we force our users to leave our application, so that they can loose their context while searching for answers on Google?
In this talk I want to talk about a paradigm for embedded help that makes documentation content available right in the application, no matter if it’s a video tutorial, Walkthrough, or page in the manual. I will also introduce EmbedHelp, an open source embeddable widget that makes it easy for non-technical authors to implement this paradigm.
From English professor and assistant dean to software engineer. How the heck did that happen? How hard was the transition? That seems…different. And what the heck are developers thinking when they say the code explains itself? These are some of the comments and questions folks ask me when they learn my background.
Included will be some commentary on learning to code, job prospects, and ways in which engineering is like grad school (for English). Also covered will be why development is an awesome career for folks who love words, grammar, and writing. Find out what’s up with developers, documentation, and denying the need for it (DID YOU SEE THAT ALLITERATION? My gawd, I’ ve still got it).
Whether you’ve thought about moving into software engineering yourself, or maybe you want to hear how one can go about learning hard, new stuff, this may be the 15 minutes during which you’ll want to skip the hallway track.
Math is a universal language but it is also primarily a visual language. People who are visually impaired or blind face far more challenges with mathematical communication than do sighted users.
If you create mathematical documentation and your math is in LaTeX or MathML form, you can use the same technologies described here. By leveraging today's technologies on the server-side (NodeJS, MathJax, MongoDB) as well as client side (MathJax), you can provide your all of your users, sighted as well as blind, with accessible mathematics.
Your readers will have the power to choose the format that works best for them. For visually impaired readers, that might be the ability to scale and zoom; for blind users it may be using a screen reader to speak math.
An overview of the problem is presented, a few of the challenges we found are discussed, and the final technical solution is described.