All talk videos will be published on our YouTube channel no later than 1 week after the conference.
A guide to getting started in open source
Open source projects are a great opportunity to grow your skills or learn new ones. Project maintainers are always looking for new folks to help out with various aspects of the project, especially when it comes to documentation. But how do you get started?
For me, this was the most overwhelming question when I first started in open source a few years ago. Coming from a background in closed source, stepping into the open source world felt a lot like stepping into Wonderland to me. There were so many new terms to learn, new ways of doing things, and, the scariest of all, I now had to do everything in front of the whole world. EEEK!
Looking back over my journey starting out as a nervous newbie and transitioning to technical documentation lead for prominent open source projects (Harbor and Velero), I'll share some lessons learned and tips on how you can get started on your adventure in the world of open source, including
- Researching your path and picking an open source project that fits you
- Gearing up for the trip by getting familiar with commonly used tools and terms
- Plotting your course and knowing what you want out of the experience
- Being ready to ask for help when you need directions
- Remembering you don’t need to get there in a day, start by setting small goals
Writing a perfect technical tutorial
As a developer advocate at Twitter, I'm often writing technical tutorials as a core part of my role. In this talk, I'll go over the process I use to source ideas for tutorials, how to start creating tutorials, gather feedback, and the next steps once the tutorial is published.
Building a style guide from the ground up: lessons learned from a lone writer
About a year ago, I joined a team that used the Google Developer Documentation Style Guide (GDDSG) for our documentation. While it met our needs for the most part, I realized that we needed a style guide customized for our product and brand. So, I set out to create a style guide just for us—as a complement to the GDDSG.
But creating a style guide is no easy task. It’s even harder when you’re a one-person documentation team and have no prior experience creating style guides. In this talk, I’ll share lessons learned from my experiences building a style guide as a lone writer, mistakes to avoid, and practical tips for anyone who wants to build a style guide from scratch.
Invisible influence — the documentation behind UX copy
The words in your favorite app may seem simple, helpful, and unobtrusive. But to get there, UX writers are playing an elaborate game of influence.
To arrive at the words you see on the screen, we juggle input from product management, design, marketing, engineering, and user research. The words we write may seem simple, but the documentation we use to get there goes deep.
This talk will show you how to use documentation to build a design rationale, influence others, and show the value of UX writing to the broader organization.
This talk will show you documentation techniques to:
Support your design decisions Build new guidelines and standards Bring your partners along on the journey Show the value of your work
If you need to convince somebody of the “why” behind the “what”, this talk is for you.
Shuffle ball change: Sashay your way to clearer API documentation
Learn how to tap into your audacious self to improve API documentation at your organization. In this talk, I’ll compare processes across a few different companies and teams for authoring, editing, and maintaining various types of API reference documentation.
We’ll touch on these topics and more:
- Discovering unexpected benefits of API-specific knowledge
- Levering bulk edits for when a reference needs an entire overhaul
- Balancing ownership of an OpenAPI spec or source comments
- Chasing developer commits
- Establishing API reference writing guidelines for developers
If you’ve ever found yourself wondering how and where to start making improvements to API reference docs, this talk may inspire you to heel/toe your way into the spotlight.
Almost None to Some: Driving DISQO's Doc Culture as a Solo Documentarian
When I was hired at DISQO as a Technical Writer, the number of engineers was hovering around seventy, and there was just one of me. With numerous Google Docs and Markdown files strewn about and much to still be documented, it was critical to take consistent action to build up DISQO's documentation alongside our documentation culture. In my talk, I want to tell the story of how we went from almost no documentation to some documentation, and how I lead this as one person, imperfectly.
Some things I'll talk about:
- Why some documentation is better than none and how to move from almost none to some with limited resources
- Building our documentation tenets (Transparency, Improved Communication, Lower Barriers to Entry)
- How I engaged people involved in building out dozens of docs over three websites as the sole Technical Writer for a 70+ member engineering org
- Being comfortable with unfinished documentation
- How I established partnerships, found my place in the organization as our only Technical Writer, and started our Tech Doc Guild
- Technical writing as part of the engineering team, and training our less-technical members on our docs-as-code process
Always complete, never finished
Often, the easiest part of work is doing it. The hard part is knowing what to do.
The documentation writer who has sat staring at a blank page wondering how and where to get started will find this familiar. A large documentation restructuring project can have exactly the same paralysing effect.
Facing a project large enough not to be completable in one go, and that won't have much value until it's actually complete, we often feel we don't know how to begin. Complex projects lure us into creating frighteningly complex plans, that we draw all the way to our envisaged finish-lines. The next thing we know we are staring at a mountain of our own making.
It's a trap! It's by no means exclusive to documentation, but we documentation writers fall into it particularly hard.
I fall into it often. I see colleagues and clients do it too.
We fall into this trap because we confuse the finished with the complete. The way out is to understand that, as a living project, our documentation will never be finished, but can always be complete.
Understanding this gives us:
- several practical, immediately usable strategies and techniques for tackling jammed documentation projects and starting out on new ones in ways that keep the work flowing
- a general approach to documentation that helps steer us around the trap, and climb out of it more quickly
- an incremental, evolutionary way of working on large documentation tasks that makes every step, from the very first one, a value-adding improvement
Above all, it turns the paralysing question of knowing what to do into a liberating act of deciding to do, by making it easy to act.
I'll discuss all these with real-life examples, and aim to leave the audience with a handy mental tool-kit that will help them the next time they find themselves facing the same trap.
Writing Documentation with Neurodivergent Open Source Contributors In Mind
When writing accessible and equitable documentation, it is important to remember that as of 2016, studies showed that 1 in 54 people are neurodivergent, and that neurodivergence is not something one ‘ages out’ of. Neurodivergent people are your fellow community members, customers, coworkers, and open source peers. As such, writing documentation without taking the needs of the neurodivergent community into account will result in not only unhappy users, but unhappy contributors also.
Writing documentation is a skill that requires effort, dedication, and commitment to improving not only the particular project you’re working on but also the wider open source community as a whole. However, technical documentation and contributor guidelines may be unclear to contributors who are neurodivergent.
Neurodivergent individuals can often face challenges in the following areas when contributing to open source and writing or reading documentation, which can include:
- Identifying a DRI for an issue if an organization or project’s hierarchy is unclear
- Implied ‘best people to contact,’ that one only knows about if they are already a member of a community
- Unclear descriptions of where to get started on their contributor journey
- Language that assumes a particular skill set or experience level with a particular technology or concept.
Through education and awareness, we can change this situation for the better, and create a more equitable and welcoming documentation community for those that are neurodivergent.
Putting the “tech” in technical writer
It is often a myth that developers get to play with more shiny stuff and tools. Over the last few years, a lot of non-tech teams have upped their game and are now actively involved with, and collaborating using the same toolchain as the rest of the technical team.
Coming from organizations where I was primarily writing documentation using tools with often standalone WYSIWYG editors and environments for over 10 years, docs-as-code (particularly writing plain text) has really been a massive change. I suspect I am not the sole occupant of this proverbial boat though. Quite a few tech writers who have made this journey would agree that it is indeed a leap worth taking.
How do they make this transition though? How do they get comfortable with the idea of plain text, command line, and automation?
In my talk, I take the audience through a few ideas and examples (both personal and community sourced) for: a. Looking under the hood (of WYSIWYG tools) b. Learning just enough Git c. Thinking in plain text d. Templates, toolchain and processes e. Faster reviews and builds
Sarah R. Rodlund
Beyond metrics: Using maturity models to develop a docs strategy
How do you measure the impact of your work? What’s the best way to communicate its value to others in your organization? What metrics should you use? Does information about page views and up or down votes actually lead to better docs? These are perennial questions for technical writers building a docs strategy.
At the Wikimedia Foundation, we use maturity models to guide our docs development and to track our progress over time. Maturity models are flexible frameworks that help us to gain a more honest and holistic understanding of our work and its impact than we can with traditional metrics alone. They allow us to decouple our definition of success from abstract numbers. Instead of telling us how far or how fast we are going, maturity models allow us to see where we have been, where we are, and where we are headed. They give us clarity about what we’re doing well and what we need to improve.
In this talk, I’ll explore:
Some metrics technical writers use to measure the impact of their work and why they fall short What maturity models are and how they can provide a holistic view of your docs strategy and its impact
I’ll also demonstrate how we use maturity models in the Wikimedia Foundation’s technical department to stay oriented and to guide our focus.
The Secret History of Libraries
Why do we care about libraries? Why are they so special? What makes them feel like secular sacred spaces? How do we capture and preserve that feeling? How do we recreate it?
This session explores what's so special about libraries, and unpacks the layers behind what makes a library a library. Open data wasn't invented in the age of the computer!
In this session, from a computer scientist with a history degree, you will learn such things as:
- why and how traditional Jewish law says that no writings with the name of God on them can be discarded, and how this led to treasure troves of resources on medieval Jews (as it turns out, people in that era who could write, would barely write anything without referring to God, so if you want a medieval shopping list, I'll tell you where to go!)
- how craftspeople in the Renaissance would use old books, and scraps of paper, to make boxes. This preserved writing never intended for posterity (posterity in the form of a box, no less!) What can we learn from this? Come and find out!
- what's the use, in 2021, of what is effectively a medieval sticky note saying "Could you please get me some wild roses? But make sure to include some that are not yet flowering!" Why do we have a 600 year old sticky note, much less care what it says?
Find out how we can create future libraries, and what we can do to preserve the libraries we have now. What even is a library? This will be a fast-paced history lesson, relating everything you hear to the modern day. Find out what's next, from the past.
Level Up - Onboarding that enables writers to thrive
How do you help a newly hired writer get off to a good start without overwhelming them? And how do you continue to support their growth?
Company onboarding frequently lacks context and resources for writers to ramp up and grow successfully, leaving writers struggling to onboard themselves and their teammates.
I’ve experienced onboarding writers from various perspectives across my 20+ year career, including:
- First tech writer at a company, establishing structure, relationships, and boundaries
- One writer among many, navigating the complexity of a large, global company
- Helping writers from acquisitions to transition into a company
- Documenting knowledge when leaving a team or company
- Doc tool support and education for writers and SMEs
- Official and unofficial leadership and mentoring
When I joined Google, I saw onboarding gaps that I’ve seen throughout my career. I brought together a team to develop writer-specific onboarding that we've used to ramp up many tech writers, editors, and tech writing managers since mid-2019. The education supports writers coming from a wide range of experience who will write for consumer or developer products, internal projects, or data centers.
This talk is for anyone onboarding a new writer, whether it's your first or your fiftieth. You'll learn about:
- Why writers are poorly served by generic onboarding
- My Google onboarding experience and how it led to creation of our education
- Our approach to creating our onboarding and how to apply it to your own context
- Selecting and prioritizing content
- Providing a path for growth after the initial education
- Scaling education, fostering doc culture, and increasing the visibility of documentarians
Is Tech Writer a Tester, and Vice Versa, Is Tester a Tech Writer?
As a person who worked both as a software tester and a technical writer, I can say that to be either a good software tester or a good tech writer, you need to be both. Tech writing presupposes you have enough technical knowledge to understand a topic and succinctly describe it to your audience. Most companies in which tech writers work actually want their own software products described in such a way that the content is easily understandable. And to get to that point, a tech writer needs to understand the product in-depth. What better way than to test it/use it by themselves as a user would? At the other side of the writing spectrum is the tester. The person who needs to make sure everything software engineers programmed works as planned. And in most cases, make sure that whoever comes after them, knows what steps to take to ensure that the new software release didn't break a legacy feature (why good regression tests exist). A well-written test script will ensure that doesn't happen. This talk will discuss the following:
- Where do tech writing and software testing overlap?
- Can you switch from one career to the other?
- Why do we love developers?
Documentation Communities: Sound Strategy or Documentarian's Gambit?
This year, like many of you, I binged on the Queen’s Gambit. In chess, a gambit is a move where you sacrifice a chess piece in the hope to put yourself in a more advantageous position. When the gambit is presented to the opponent, they can either accept or deny it. If the strategy works for the opponent it is considered to be sound.
Open-sourcing your documentation holds the promise of a huge pool of dedicated volunteer writers, but at the risk of reduced quality and coherence. It is easy to think that more help means less work, but is that really the case? What is the impact on the organization and on the release schedule?
At ScyllaDB, we considered these questions and decided that 2020 was the year to go open. Our code was already open-sourced, but our documentation was not. As the company grew, the docs became harder to manage, especially with only one dedicated technical writer. We considered the risks of how much time we would spend and wondered if it would impact the release cycle. Our solution included recruiting our developers to be active contributors and after we saw this was successful, we open-sourced our documentation. The decisions we made were not simple, we had to endure a painful migration, and we learned many valuable lessons along the way. In the end, we concluded that the time spent gave us a good foundation and we feel we have built an atmosphere where contributors would feel welcome and have created design decisions to make it easy to contribute to docs.
This talk explains how we created a documentation community and created an atmosphere where everyone involved understands their role and is eager to help. Our work is not completely done, but by the time the talk is held, we will have gained enough experience to share what we thought about and what we have learned.
You will receive tips, best practices, examples, and anecdotes that discuss:
- Recruiting and onboarding contributors: Find new writers and bring them up to speed
- Keep existing contributors writing: Methods and tools for collaboration, motivation, and reviews with teams inside and outside your organization
- Get Everyone on-board: How to align the entire organization to think about and contribute to the documentation. Convert the naysayers into cheerleaders.