Workshop: Learn how to Git
Git is becoming the defacto place to store source code. If you want to integrate and stay up to date with code, you should also be keeping your documentation there. This tutorial will take you from feeling uneasy about interacting with git to making it feel like something you can 'git' the hang of.
Learn how to Git with Matt Desmond, who is a technical writer-turned-trainer for GitHub. Take part in hands-on keyboard exercises that will removes the guesswork out of managing your development process using Git.
After attending this session, students will:
Conquer the different Git commands
Actually understand what that StackOverflow answer means
Be able to have a conversation about branching strategies (and understand what a branch even is)
Become a collaboration machine!
Tickets to this workshop are sold seperately. You can buy your ticket here.
Workshop: Structuring and writing documentation
What is a documentation structure, and why does it matter to developers?
Lots of developers get asked to write their own documentation, especially internal documentation and onboarding. In theory, this is good because they know the problems they are writing about and don't need to spend time explaining them. In practice, developers avoid this work because they don't have a good idea of how to start and can't evaluate whether they have succeeded.
This workshop is designed to teach you a few basic theories of technical documentation, such as task-based topics, reusable content, and writing for an audience. After the overview, you'll learn techniques for writing bug reports, error messages, and onboarding instructions in a tool-agnostic, repeatable way. You'll leave this workshop with a handful of techniques, templates, and tests that will improve your team's communication and your life as a developer.
What is structure?
What do I really need to know?
How to write an error message
How to write a bug report
What is transparent to writers?
How do you interact with the team around building stuff.
The structure will be 60-90 minutes for basics, and then the rest for workshops.
Tickets to this workshop are sold seperately. You can buy your ticket here.
Everyone's a player (in a mid-90s MUD)
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.
Testing: it's not just for code anymore
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.
Unconference Session: Write the Docs Meetup Groups
Write the Docs is filled with great conversations about documentation. If you want to continue the conversation, we have Meetups on four continents.
If you're a Meetup leader, or want to start your own Write the Docs Meetup, come to our unconference session. We'll facilitate while current and future Meetup leaders discuss strategies and tips for better Write the Docs Meetups.
Building a community
Diversifying beyond technical writers
Sharing the organizer role
Evangelizing WTD to development and other groups
Building navigation for your doc site: 5 best practices
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 5 design principles:
Entry point. Design the entry point to your system to orient users and allow them to easily get started.
Hierarchy. Create a hierarchical outline of the content to help users both understand and visualize the body of information.
Modularity. Break up content into independent topics that can be viewed, understood, and updated independent of the whole.
Progressive disclosure. Layer the information so that you don't present everything at once but rather make some content available only at secondary or tertiary levels.
Wayfinding. Provide navigational signposts \u2014 such as breadcrumbs and workflow maps \u2014 to help orient users as to where they are in a larger system.
You have already succeeded: Design critique guidelines make feedback easier.
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.
Only Interesting Conversations: The symbiotic relationship between docs and support
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.
Unconference Session: QueerTea
QWERTY: Queer Writers Enjoying Relaxing Tea Yearly! Join us for a cup and friendly chat with fellow LGBT+ documentarians. You aren''t here alone. Dvorak typists welcome too, but you''ll have to create your own puns.
Error Messages: Being Humble, Human, and Helpful will make users Happy
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.
Interviewing and hiring technical writers: the Siberian way
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?
Treating documentation like code: a practical account
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.
No Community Members Were Harmed in the Making of This Doc Sprint: How we ran a 48-hour event to collect community wisdom into a guidebook for newsroom developers
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
The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization
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.
Caring Systems: Documentation as care
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.
Bootstrapping Docs at a Startup
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?
Unconference Session: Release Notes: What's Working (and Not Working) for You?
We're interested in revolutionizing release notes. Now with cloud services and their continual and more frequent releases, we need to find a balance between comprehensive, helpful, and accessible release notes. We want to take this opportunity to brainstorm and discuss what's working and what' s not.
We created a WTD slack channel: #release-notes @ writethedocs.slack.com to continue our discussion about release notes.
Unconference Session: Worst-case Scenario Planning
The last thing you want to think about is work when you or someone you love gets a life-threatening illness or has an accident. We will cover tips, precautions, and stopgap measures to take when you're the linchpin (because you hold Institutional Knowledge or have been tasked to gather it) to your team/company, but suddenly have to prepare to permanently leave or take medical leave from a position.
Even Naming This Talk Is Hard
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?
Start with the tasks, not the endpoints
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 workflow when considering everything from overall information architecture, to deciding which content assets to prioritize, to refining the tone used throughout your developer communications.
Intelligent Documents and the Verifiability Crisis in Science, Tech Writing, and Life
This talk is about the verifiability crisis in science, politics, and technology, and how methods developed to address verifiablity in statistical publishing can be adapted to other areas such as technical writing.
In 2015, a group of researchers set out to replicate the results obtained in a set of 100 published psychology research papers. It turned out that only 29 out of the 100 could be replicated.
In the 2016 elections, so-called "fake news"--fabricated news published on venues such as Facebook--influenced many voters in their choice of candidates.
In the field of technical writing, it is not uncommon to discover that technical documentation is inaccurate. Although the docs might have been accurate when first published, the underlying technology evolved rendering the docs obsolete.
Academic, public-policy, and business decisions are sometimes made after accepting published (mis)information at face value. The costs can beconsiderable.
The information often arrives in the form of an electronic document, such as a web page or PDF file. To verify the information, someone has to "fact check" it. But what if the document could, in some sense, "speakfor itself" and demonstrate the veracity of what it is saying?
In response to the verifiability crisis in science, statisticians havedeveloped technology to create "intelligent documents" that not onlyreport the results of a statistical analysis, but can also re-create theanalysis itself.
Do you know a runbook from a flip book? How sysadmins use documentation
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\u2014which 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.