Open source communities attract and boast passionate, idealistic people, and many of us invest copious amounts of time and effort to contribute to our projects and support our communities. This underlying emotional attachment can make us more vulnerable to elevated stress, burnout and conflicts. And then there are those of us who also manage mental illness. More often than not, we suffer these struggles in silence, feeling (and fearing) that we’re alone in our trouble. Here, our communities can make a huge difference, by building a positive and safe environment where we can blossom and support ourselves and our peers, and feel included. This talk will take a look at open-source communities through the eyes of various mental well-being issues and struggles, show various things that some communities already do. We will also cover several new initiatives from the community around Django, a common open-source web framework for Python, to further promote the well-being of our community members. This will hopefully inspire more communities to help foster healthy minds in a healthy environment.Watch "Healthy Minds in a Healthy Community" on YouTube.
Feedback is a big deal. As tech writers we want to receive adultation when the docs rock, or constructive criticism when there is cleanup required. Or EVEN BETTER, we want the engineers/community members/reddit readers/clowns giving the feedback to come on board and help fix the problems.
But. Actually tweaking the signal to noise ratio to something useful is really difficult. Especially when you are curating a site as enormous as MDN, the content of which is open licensed, multilingual, and open for public editing.
In this talk, MDN writer Chris Mills discusses topics such as how to choose the right feedback mechanism(s) for your situation, how to stem the torrent and get the right kind of feedback and contributions (actually useful), effective begging, stealing and borrowing, and how to balance being firm and keeping control of your product with being diplomatic and being able to sleep at night.Watch "Feedback handling, community wrangling, panhandling" on YouTube.
As documentarians, our primary goal is delivering the content that users need in order to use our products. This might sound simple, but we are often writing about complex systems, which will be used by people of varying skill levels. Our final publications may have all the words in the right order, but sometimes our biggest challenge is getting access to the right content in the first place.
Deciding on what is the right content can often be hard, and extracting it from the development team can be even harder. Some of us might be able to read the codebase to decipher what information a user will need. Some of us might get to sit in planning and strategy meetings to gain a thorough understanding of our user and their documentation requirements. Most of us though will find something in the middle - we sit with developers and engineers, build relationships, and elbow our way into their process.
This talk will look at several ways in which to mentor your engineering and marketing specialists so that everyone in your team can contribute to the documentation process. I call this "Documentoring" - its about training the people around you to understand the requirements of a documentarian, and to truly value the docs as part of the product lifecycle.
Through my experience at IBM, and then at a small startup in Bristol, I've seen (and tried) various techniques at getting everyone in your team invested in quality documentation. I'll share stories of my successes and failures, and show you how documentation really can be a team effort, even if you stand alone in your company as the sole owner of the docs.Watch "Documentoring: Growing a "Love The Docs" community" on YouTube.
You have your content moving at a swift pace, your documents are getting reviewed in a timely fashion (surprise!) and you are nicely heading towards your release milestone. The only thing missing are some key screenshots that you need to put in before you publish your documentation. What you get instead are some hideous images posing as screenshots, that were captured randomly, bears no resemblance to your instructions and would make no sense whatsoever to the end user.
We (documentarians) know how this usually pans out.
This talk is about when bad screenshots happen to good writers.
In my presentation, I will talk about:
Outside of my technical writing work for software projects I have been creating a board game. A board game also requires mechanics to function and players to clearly understand how these mechanics work to use and appreciate fully.
As part of my research for writing game manuals I looked at manuals for furniture, electronics, and cars to see how they explain to users how to setup and use their products.
In this presentation I will look at how the technical writing skills of different industries can learn from each other.
This will include:
And as part of looking at these case studies, the presentation will cover:
And by the end of the presentation I hope that everyone will have learnt a lot from each other and realize that we're all trying to achieve the same thing(s).Watch "Beyond Software - Learning from Other Technical Writers" on YouTube.
The success of an API crucially depends on how well its documentation meets the information needs of software developers. But what information do developers need? What information do they want, and what information are they actually using when starting to learn a new API and solve programming tasks with it? In this talk, I will present the results of some empirical studies I conducted with my team to better understand the information needs of software developers. One the one hand, we ran more than 20 semi-structured interviews with junior and senior developers and asked them – among other things – to tell us about the questions they raise first when approaching a new API, the type of documentation they look for, and general expectations and experiences regarding API documentation. Key findings derived from the interviews were then followed up on by a standardized survey in which more than 110 developers participated. Our second study took a different approach. Instead of asking developers what they find important about API documentation, we asked them to solve a few tasks on a simple (REST)-API that was unfamiliar to them. The goal of this study was to observe how the developers approach the tasks and which pieces of the documentation provided with the test API they actually use. Besides presenting the design and main findings of our studies, I will also discuss implications the results may have regarding the contents, structure and design of API documentation.Watch "API documentation: Exploring the information needs of software developers" on YouTube.
Writing professionally in English as a non-native speaker is a terrifying task sometimes. "The limits of my language mean the limits of my world." You have less limit when writing in your mother tongue. And you may experience hard boundaries when you have to deal with other languages on a professional level.
As a beginner (non-native English) content creator, I had hard times during my work. Most of the problems came from me because the lack of confidence and the lack of practice. To grow faster, I had to build a process (rather a routine) that I can follow during my work on a daily basis. I had to find the most effective supporting tools. And maybe the most important: I had to figure out how can I keep myself motivated in spite of every failure.
How can a junior writer overcome the initial difficulties? My presentation tries to answer this question through real life examples to help other juniors in their struggles. And offers some writing tools, habits, and methods that may be worth to take a chance.
I would like to present what I've learned during my journey so far.Watch "Writing as a non-native speaker" on YouTube.
The Write the Docs community has been growing over the past few years, and we're incredibly happy to see the wide diversity that it contains. In the beginning of 2016 we put together a survey to investigate how people are doing their jobs, what the current status is of documentation, and what the future will bring. We're calling this effort "Poll the Docs".
Thanks to the 100+ participants who already filled it out and shared their experiences and thoughts about documentation. We will be able to share insights about the demographic background of the community, how documentarians usually start working in this field and give an overview of the most supported practises, tools, languages and skills.Watch "Poll the Docs" on YouTube.
The aviation industry has made flying long distances at high speeds one of the safest ways to travel. How did they do it? In part with the help of the humble but effective checklist! In this talk, you’ll learn to adapt the checklist practices of high-risk environments, like flight decks and operating rooms, to avoid mistakes and improve your documentation process.
Have you ever missed an important step that you’ve done a hundred times before, or are you worried that you might someday? Or have you ever repeatedly made the same, avoidable mistake? A well-designed checklist might help you avoid errors large and small and increase confidence in your workflow. In this talk, you’ll learn:
Inspired by research and practices in aerospace safety (such as “Human Factors of Flight Deck Checklists: The Normal Checklist” by Degani & Wiener), medical safety (such as “The Checklist Manifesto” by Atul Gawande), and cognitive psychology (such as “Human Error” by James Reason), this talk will guide you through the process of making and using checklists in the day-to-day work of creating documentation.
From what distinguishes a checklist from a to-do list to developing checklist habits, you’ll learn how to use checklists to help you write the docs.Watch "Checklist the Docs" on YouTube.
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.Watch "What Writing Fiction Teaches You About Writing Documentation" on YouTube.
Interaction between incorporated software-systems is often realized via application programming interfaces (APIs). The API-documentation explains how to use the API. If it misses important information, serious misunderstandings between the API’s consumer and provider can be the consequence.
I my talk I will show how meaningful names in the source-code can help finding gaps in the API-documentation. My findings base on my project-experiences and a cross-sectional study of a corpus of more than 186.000 web service-operations. I would like to share the 20 description-patterns for API-documentation I found so far. They provide detailed recommendations description of specific operations. The talk closes with a comparison of classical „swagger-like“ API-documentation with the presented approach.Watch "Using meaningful names to improve API-documentation" on YouTube.
Do you know what the support agents are doing over in their corner? It’s not all cat gifs and angry users. There’s real value to be found in working together with your support team. They are a direct line to your users!
It can definitely be difficult to bridge this gap between disciplines, but your goals are 100% the same: help the customer do The Thing. Because support literally spends all day talking to customers, they have a ton of amazing data about the effectiveness of documentation, and the tasks customers are trying to accomplish.
Building a better relationship with your support team will help you build a better relationship with your users. I’ve seen first hand how coordination drives a well executed user experience all the way from self service to hands-on support. Work together better and see tangible results in your user happiness!
In this talk, I’ll show you: · the value of having support and technical writing aligned · how to break down the silos between teams and work effectively together · how to access and use the glorious data that support is already collecting · the metrics that matter for support-led user assistanceWatch "Documentarians and Support: Work Better Together" on YouTube.
What are the characteristics of a great documentation set? Completeness? Accuracy? Style? Format? No! A great documentation set is one that meets its objectives, and sometimes the barrier to greatness is not dedication, skill, or passion, but a reluctance to let things go. Every document we publish should reach a certain quality threshold - but that threshold varies depending on its audience, the maturity of the project, and the overall project goals. What matters is not that docs are perfect, but that they are good enough.
But how to determine if a doc is "good enough"? This talk will cover how to:
We're all overloaded. We're all stretched for time. Every hour we spend making a doc better than it needs to be is an hour stolen from other projects where we could have more impact. Choosing "good enough" doesn't mean we're lowering our standards; it means we're choosing appropriate standards and prioritizing correctly. Don't let the perfect be the enemy of the good.Watch "Pretty hurts: Why better trumps best" on YouTube.
So you had an idea for an awesome software product and started to build up your team of engineers around it. Two things are almost inevitable: you chose some super cool programming language like Clojure and you're doing Scrum for the process. Good for you.
When your company grows, you end up with multiple Scrum teams. But you also end up with new activities: documentation, blogging, demos, submissions to conferences to show-off your awesome heap of Clojure. How are you going to get all of /that/ done?
"The book" tells you to mix all these activities in with your Scrum engineering teams. "The Book" was also probably written by someone who has never had to do devrel in their lives (or, who hates devrel engineers). Numerous problems exist at the interface between product engineering and devrel and the result is your devrel backlog can get backed-up.
Dr. Paul (not a real doctor) has the laxative you need! In this talk he presents his experience of structuring multiple Scrum teams at Crate.IO in order to loosen-up the devrel backlog: ensuring highly quality feature documentation, getting out those blog posts and showing-off our lovely heap of Clojure*.
*Crate is written in Java.Watch "Postulating The Backlog Laxative" on YouTube.
Most discussions of information architecture (IA) treat it as a high-level discipline: it’s that thing we do site-wide, obsessing happily about taxonomies, hierarchies, and metadata, so that our content is more maintainable, navigable, and searchable. But what do your readers do when they actually find the information that they’re looking for? They read it. They read the words. Where’s your information architecture now?
In this talk I’ll identify a few different ways that we can apply IA principles productively also at the micro levels of paragraph, sentence, and phrase. We’ll focus on a series of syntactic structures that prove their special architectural significance, based on the results of ongoing content testing at docs.shopify.com and on recent work in the field of psycholinguistics. These key examples show how far we can improve sentence processing speed, and thereby reader engagement, when we use grammar deliberately as information micro-architecture. The composition and revision strategies that this approach suggests are especially useful for anyone who’s writing, editing, or optimizing content for use at scale.Watch "Information micro-architecture: grammar, syntax, and cognitive rhetoric" on YouTube.
Operations tech writing encompasses both hardware and software, and the challenge is coming up to speed on the intersecting parts of these 2 disciplines. More than any other type of tech writing, operations TW is the art of supporting highly technical, cross-functional teams. Most companies create super secret, bleeding edge technologies to make their data centers efficient, powerful, reliable, economical, and, hopefully, green. There are few opportunities to gain background info to bring yourself up to speed and feel confident about your technical prowess.
This is a little talked about area of TW that's growing in importance and demand. At Google, it's been difficult to find writers qualified to handle the cross-functional complexities/hit the ground running, and the ramp up is steep. I'll address the demands of working in this challenging but fascinating field, as well as some cultural perks such as working with physical engineers (mechanical, electrical, manufacturing), travel, and developing one's photography skills -- and saying goodbye to capturing screenshots.Watch "Operations Technical Writing for Data Centers" on YouTube.
Two years ago, Atlassian had no consistent voice guidelines across its content channels and product suite, creating a disjointed brand experience. Today, our Information Experience writers now own the Atlassian voice and tone, and are teaching everyone from developers, product managers, designers, and marketers how to voicify their content.
In this talk, Sarah Karp (Information Experience Team Lead) will answer the following questions:
Along the way, Sarah will share ways in which the Information Experience writers have applied voicify guidelines across the entire organization. She'll also share a couple of lessons on voice and tone gone wrong and how to learn from those mistakes.
At the end of the talk, you'll come away with an understanding of why successful products have a distinctive voice and tone. You'll also come away with great examples of voice and tone wins (and fails), and practical tips about how to create voicify guidelines for writers and non-writers alike.Watch "Watch that tone! Creating an information experience in the Atlassian voice" on YouTube.
To prevent stale content and achieve a high standard of alignment with products, documentation must be a required component of the release cycle. At Pantheon, this means delivering each component with similar precision and trust. Documentation workflows must evolve to stay instep with agile and automated product pipelines.
In addition to sharing lessons learned, this talk will explore Pantheon’s strategy for delivering high-velocity docs:
Treating docs as code, an approach that more and more teams and companies are moving toward, involves more than putting the two together in a repo. We discuss some of the details that often get lost in as dev and docs learn to work together in new ways. Because if all we do is put doc files next to code files in source control, or use parts of the same workflow for code and docs, we're still isolating docs as a separate sort of responsibility, free from the obligations of systematic review and testing without which code would never be accepted into production.
Some missing parts of this newer approach to documentation workflow that we'll discuss include: