Doing maintenance or updates to existing content can be challenging to justify to your organization. There’s even a community who call themselves “The Maintainers” who identify as being “interested in the concepts of maintenance, infrastructure, repair, and the myriad forms of labor and expertise that sustain our human-built world”.

On our writing team, we had a robust process of evaluating whether, when, and how to update our legacy tutorials. We selected tutorials for maintenance in essentially two different ways: one (“Tech Debt”) is if we wanted something to link to from our newer content, and the other (“Opportunistic”) is metrics-driven.

In this presentation, we’ll share some of the metrics we used, explain the thresholds we used for determining whether to update our older content, and demonstrate the measurable results we have from increasing traffic to the content. We used several of our own top-of-funnel traffic metrics, comparing against customer conversions – our goal was to do maintenance that consistently shows an improvement on all of these metrics. You’ll learn how we pitched, scheduled, and edited our own submissions to maximize their value to our audience.

You’ll also learn about the team that authored and edited that content, and how we prioritized and undertook that work. From an SEO perspective, this maintenance is a great way to improve deep linking across our community site, and from an everyday work perspective, it’s a great way to balance the need to always be publishing new tutorials with the time to look after what we already have.

When presenting an API to a customer, that customer's developers depend on accurate and clear API documentation to understand the API contract that their code will interact with. How do we make that documentation accurately represent behavior, and also look good? How can we handle APIs spread across multiple microservices and teams in a company, and make the documentation all look consistent instead of looking like none of the teams have ever talked to each other?

Plenty of tools already exist for developers to write code that documents itself and creates its own OpenAPI spec files. However, developer teams do not always have the technical writing background needed to adequately describe APIs for customer use. Technical writers can make excellent customer-facing documentation, but being isolated from development and trying to keep up with field definition changes, behavior changes, and various breaking changes, is an onerous task. And how do we make it work with legacy code?

This presentation will show how we are pulling all of this together and creating a new process for creating API documentation that we can be proud of. It will show how we are creating a partially automatic, partially manual process that is fault-tolerant and flexible enough to handle differences in technical approaches, customer needs, and personalities.

What questions will this talk answer?

• How do I make a whole bunch of different services look uniform and coherent?
• How do I create a process for creating OpenAPI spec files that are presentable to customers?
• How do I get technical writers, developers, and managers all working together?
• How do I convince people that API documentation is a priority for everyone, not just technical writers?

And what can we learn from 24 hour psytrance at Burning Man that will help people work together, anyway?

This talk shares practical evidence-informed ways to design and integrate visuals into your documentation. The ultimate goal of including visuals in documentation is to focus the learner’s attention. However, too often visuals end up being scrolled over or worse distracting learners. The learning sciences provide a rich perspective on images for learning. While instructional designers have a complex list of terms to describe visuals for learning, I’ll break down the key terms to understand when categorizing visuals. Moreover, I’ll share how to include different visuals that support the aims of your documentation–instructing learners.

This talk will focus on practical takeaways from evidence on how to best integrate visuals into instructional content. Firstly, I’ll bust the myth of learning styles. Then, I’ll explain why carefully chosen visuals can support all learners to get more out of your written content. I’ll run through do’s, don’t’s, and nice-to-haves when considering diagrams or other visuals within your documentation. Finally, I’ll provide some ideas on how to get started updating the visual language of your documentation.

Developer advocate and technical writer Linda Ikechukwu launched her technical writing blog, www.everythingtechnicalwriting.com, in 2022. In just over a year, she’s interviewed over 10 prominent technical writers/documentarians on their career through her Tech Content Creator Series.

From how Alexandra White, who had previously worked at only small unknown startups was able to stand out during Google’s technical writing interview process by submitting a style-guide formatted docs, to Amy Bun's account of how she convinced her manager to create a new content design role for her on the Github documentation team. These experienced tech writers were eager to share the lessons they’ve learned while navigating their careers, their biggest challenges and how they overcame them, and mistakes they made, to help others avoid the same stumbling blocks, embarrassments, and missed opportunities.

This talk summarizes these once-in-a-lifetime lessons from seasoned industry technical writers for all newcomers who want to climb the ladder faster. Topics discussed will include:

• Best practices for interviewing for a tech writer role
• Levelling up as a tech writer without software engineering skills.
• Tips for freelancing as a technical writer.
• Transitioning from tech writing to other careers within your company.
• Transitioning from senior tech writer to management
• Working with managers who do not understand the importance of technical writers

In 2020, I was hired by Splunk to build a customer-facing, internally crowdsourced use case and best practice repository. The project goal was to stop gatekeeping expert knowledge that was previously limited to high-spend customers and make it accessible to all customers through self-service. The larger business goal was to improve our product adoption and customer retention rates.

Over the last three years, my content strategy has continuously evolved, and Splunk Lantern has become a comprehensive customer success center. I faced so many challenges during this time, but what I didn't expect most of all was how much of my role would be marketing, promotion, and communication. Just because you build it, doesn't mean they will come.

In this talk, I'll share what I learned about:

• Winning, and sustaining, support of executives for a new documentation project
• Helping managers encourage their team members to contribute content
• Getting over impostor syndrome and learning to promote your project internally
• Finding ways to reach customers and get them excited about your site
• Ensuring continued awareness as new employees and new customers join

If you are tasked with creating a new, crowd sourced knowledge base or if you are managing a knowledge base with low usage or low internal support, this talk is for you.

Artificial Intelligence (AI) has been making strides in various industries, but there is a common misconception that it will eventually replace human technical writers. This talk aims to dispel that myth by presenting arguments and evidence on why AI will never fully replace technical writers.

We will examine the current limitations of AI in areas such as creativity, empathy, and problem-solving, which are critical skills for technical writing. Additionally, we will discuss the importance of human intuition, critical thinking and subject-matter expertise in technical writing and how AI falls short in these areas.

We will explore the ethical and moral implications of relying solely on AI for technical writing such as accountability, bias, and transparency. Talk will provide a nuanced perspective on the relationship between AI and technical writing and the role that human technical writers will play in the future and will highlight the unique value that technical writers bring to the field and why AI will never be able to fully replace them.

In a 2019 interview, documentation veteran Pavi Sandhu cited a very reasonable 10:1 as the ideal ratio of software developers to technical writers, positing that a writer can support two scrum teams. However, in case you were wondering why you feel busy at work, according to the U.S. Bureau of Labor and Statistics, in 2021 there were 30 software developers for every 1 technical writer.

I work at a software company where the developer-to-writer ratio is, conservatively, 200:1. But this is not a talk about the ideal developer-to-writer ratio. It’s not a talk about convincing your org to hire more writers. It’s not even really a talk about how to grow the team.

This talk is about how my docs team survives, nay, thrives in an organization where we are ridiculously outnumbered. It’s about a culmination of good choices we made (and continue to make) based on leaning into the huge ratio rather than fighting it.

It’s exhilarating to be part of an incredibly productive docs team! I’ll talk about how we designed our roles, processes, infrastructure, and deliverables to optimize for the needs of a large (and growing) product and engineering organization. Even if your docs team isn’t quite as outnumbered, come hear about strategies that can make your docs team more focused and capable:

• Implementing extreme docs-as-code and minimizing maintenance overhead.
• Providing focus for writers.
• Defining and sticking to service-level agreements that go both directions.
• Fostering a “docs matter” mindset with product managers.
• Building a strong, resilient team, and what that looks like.

It's easy to assume that the "technical" portion of technical writing is adherence to rules: document specifications, style guides, and the like. But so many of the alleged rules of English come from decades-old myths or the whims of long-dead grammarians. How can we, as documentarians, ensure that the rules we follow reflect excellent contemporary writing, as determined by both the world at large and by our industry-specific language communities?

My answer to this problem is to constantly apply my training as a descriptive linguist to my technical writing practice. I'll show how to apply basic methods of corpus linguistics to quickly answer usage questions, drawing on resources as large as the 200 billion words in the Google Books corpus or as small as a single Figma file shared among a few teammates. These tools can quickly reveal patterns of existing usage, preventing us from imposing unnatural choices on our writing.

Adopting a descriptive view lets us document our products the same way we talk about our products, eliminating a translation step that opens up the risk of introducing factual errors. Ultimately, building linguistic consensus within our teams and addressing our readers in language that feels familiar builds truly communicative documentation, not merely "technical" writing.

“It’s levels to it, you and I know”

— Kendrick Lamar

Users visit docs to accomplish a goal. When a product is new, it’s relatively simple to construct a good docs experience with a streamlined getting started guide and a few concepts. As the product grows more complex, with added features and alternative ways of accomplishing similar user goals, the docs swell in volume to keep pace. This can lead to poor user experience of a docs site, with users being directed to deep, technical guides that don’t answer their simple questions. And when docs fail to provide the most important and relevant information to users, users get frustrated.

At Stripe, we’ve developed a simple framework that helps us develop new content and assess and revise existing content to create holistically consistent information architecture (IA) and an improved user experience. The basic idea is that we should think about three main levels of content: orientation, decision, and implementation. Each level provides a different type of information that users are likely to need at different times. Writers (and other docs contributors) should be aware of these levels as they create or reorganize the IA for new products and content. Ideally, following this framework ensures that we'll create an experience where users:

• Don't land on the wrong type of content
• Know where they are in the docs, where to go next, and how to go back if they need to
• Accomplish their goal (like complete their Stripe integration successfully) while having a surprisingly great experience

In this presentation, I’ll explain how we developed this framework, compare it to other similar frameworks, talk about how we’ve used it in our docs, and how others can start using it.

Many technical writers want to implement docs-like-code and must deal with organizational resistance in the form of objections.

Technical writing has its own set of challenges. What happens when you want to introduce a new docs-like-code system and workflows? If you’ve tried or considered it and encountered organizational resistance this talk is for you.

After a brief intro to docs-like-code, we’ll overcome each of the 10 most common objections to implementing docs-like-code.

1. Lack of familiarity with Markdown or other document formatting languages.
2. Perceived lack of features compared to traditional word processors.
3. Resistance to change from established workflows and tools.
4. Concerns about collaboration and version control.
5. Uncertainty about the future of the technology and lack of widespread adoption.
6. Difficulty integrating with other tools or systems in use within the organization.
7. Difficulty in handling more complex formatting requirements.
8. Challenges in managing large documents with many dependencies.
9. Inability to handle multimedia content, such as images or videos.
10. Lack of support for real-time collaboration and feedback.

How did a two-person technical writing team have 100% of their 200+ article, image-rich, 30-language Intercom help center up to date within hours of a major software redesign release? Release-readiness practices!

Keeping a software help center up to date with continual product changes can be a struggle, but it doesn’t have to be. It can even be a delight! For the past two years, the Webex Events help center has been day-one release accurate through a combination of careful planning and constant communication with product teams and stakeholders. This means that customers, support, sales, and marketing are all equipped with the latest information so they can act and learn with confidence.

In this talk, I’ll discuss:

• What “release-ready” means
• The benefits of release-ready documentation
• Processes and tools we use to keep our help center day-one release accurate
• Challenges we’ve had to overcome
• Tips to open lines of communication, make helpful friends, and achieve day-one docs

In the software industry, welcoming and empathetic communities don't form by accident—it takes intention, effort, and commitment. Our Write the Docs community is special today because this has been a priority since the first conference 10 years ago. Inclusive language is one of the tools we use to nurture this environment, but it's often misunderstood (and sometimes disparaged) as a list of rules to memorize just to avoid offending anyone. How can we improve this approach?

Trauma is complex, but can be succinctly described as a lasting emotional response to distressing events one has lived through. By examining empathy and inclusive language through the lens of trauma, we can:

• identify and evaluate potentially problematic language in advance
• understand how and why problematic language may negatively affect people
• advocate for inclusive language, even against resistance

Trauma is far more widespread than we might first imagine, but we can avoid the dynamics that may bring those emotional responses back to the forefront. The words we choose genuinely matter.

NOTE: Trauma is a heavy subject to examine. Content warnings will be provided both at the beginning of the talk and immediately prior to each slide they are relevant to. Please prioritize your well-being.

Laboratory technologists must be precise, concise, and consistent in their work to assist clinicians in making critical decisions. Sound familiar? The work of laboratorians is parallel with documentarians in any field!

The essential tool that helps the lab achieve this goal is our SOPs (Standard Operating Procedures). SOPs are the foundation to the diagnostic laboratory - many lab errors can be avoided with consistent adherence to written procedures. An array of documentation in the laboratory is essential for accurate results, consistent and cohesive judgments on subjective evaluations, and for communicating test results clearly.

Each specialty in the laboratory is responsible for the development and maintenance of their own department’s documentation. This is often viewed as a burden. Most laboratorians are not writers, and the added responsibility of technical writing is not viewed favorably.

That’s what I aim to change in the laboratory! As a documentarian AND laboratorian, my goal is to encourage my fellow lab techs to take ownership of their procedures and inspire them to take pride in their writing.

In this talk we’ll discuss:

• What makes a good SOP from the laboratorian’s perspective
• What are the attitudes of laboratorians toward documentation? How do we inspire non-writers to take ownership of their docs?
• What do laboratorians look for in documentation? Often in high-stress situations, what works and what doesn’t?
• What the lab experience can teach technical writers