The quality of content in documentation is key to successful documentation, but what about the stats? We hear a lot of numbers like Self Service Score or pageviews, but not a lot is mentioned after that when it comes to how to monitor the success of your content on a user level.

In this chat, I will explain what stats to look to understand how your user is utilizing your documentation.

We will also explore how to figure out:

• what users like or dislike about your content.
• what parts of your layout works and what just doesn’t work.
• what the gut instinct of the user when landing on a document.
• if the user is getting what they need from your documentation.

I was a technical writer before I even knew that that job exists. I did a lot of teaching, writing, creating video instructions, etc. but I never called my self "Technical writer". Only when I got my first contract as a technical writer I've realized that I almost every job that I had has prepared me for this career. I have realized that my writing path has started back in high school.

At the end of my high school education, I had to write a thesis. I've written 77 page manual about a Linux and how to set up the classroom to use it. It was, in fact, a manual with a set of instructions for the next generation of students. At that time I was already doing another kind of writing, graffiti writing. As you may know, the person that does graffiti is called a writer. There are more similarities between creating graffiti and creating technical documentation than you may think.

In this talk I would like to show you what have I learned over the years of writing, both graffiti and technical writing. Choosing the medium, creating first draft, review process, setting the right tone and style that you will use, knowing your audience, teamwork, etc. Those are just some of the things that in my opinion processes of creating graffiti and technical documentation have in common.

This talk is a summary of observations from being a new technical writer in a workplace that used to be office-first and suddenly switched to remote-first for the very obvious reasons of COVID-19 pandemic and the subsequent quarantine and social distancing measures.

Some elements and stages of traditional office onboarding just don't work in the "new normal." This is a talk about the mistakes I've made and the issues I've encountered so that other documentarians don't have to. Plus, I'll share the lifehacks that do work.

People who either already work as tech writers (or as other IT-related professionals) and need to onboard new colleagues or tech writers who'd also found new jobs during the pandemic will find this talk useful. I'll share the insights and recommendations from my own practical experience - frustration, camaraderie, getting used to the practices in place, and setting new policies to accommodate the larger team and the remote work-style, and making it all work.

How to encourage and help your community to contribute to your developer documentation? In this session, Diana Lakatos shows you various — fully remote — processes platformOS developed to help community members contribute content and code to their UKTC Award-winning developer portal.

Processes

• How the platformOS team developed a fully remote editorial workflow that everyone can be a part of (developers, writers, product owners, etc.)
• Why they follow the docs as code approach and how they implemented it through GitHub
• How they facilitate the contribution of code and content
• How they continuously improve contributor experience and reward contributions

Tools

• How they iteratively developed their Documentation Style Guide and how they use it
• How they help contributors by providing templates for specific types of content (concept topics, tutorials, etc.)
• Why they chose the Markdown format and how they use it

Communication

• How they communicate with community members
• How they collect and use feedback from their community for all aspects of their documentation (content, design, navigation, etc.)
• How they encourage people to write who are otherwise not confident in their writing skills or don’t enjoy writing

That little bit of extra love and care is what turns a dessert into a delight. So what about your product? Why not bake some of that sweet, sweet documentation right in?

Together, we'll learn that the perfect blend of product and documentation creates even more value to your users, teammates, and organization by making your content the icing on the cake. Here's why: - Dotting your UI with help content creates an intuitive flow of information for your users - Baking documentation into your product development process ensures it's viewed as essential to your team's success - Mixing answers to common questions into your app experience helps leaders reduce support burden and increase the perceived value of your product

I'll share the recipe my team followed to whip up a new app with documentation baked in. We'll walk through steps like: 1. Pre-measure the ingredients for a rich user information experience 2. With designers at room temperature, gently fold UI and documentation content together 3. Separate portions of content for reuse and spread within your product and help center 4. Write text for UI and long form documentation together until the experience is solid 5. For extra value, sprinkle marketing content with documentation to taste

Feeling inspired, hungry, or both? Let's head to the content kitchen and create something spectacular.

Hoarder. The word brings to mind some elderly person creeping through a dim house filled with piles of years-old clutter, not a 350-person technology department. But with more than 20,000 Confluence pages across 34 different spaces, what else would you call us?

True, you can't just blame the current team. The average page was 3 1/2 years old, and the oldest almost a teenager. A quarter of the pages had last been updated by people no longer with the company, and nearly a third of them hadn't even been looked at for more than a year.

But even if we'd inherited the problem, it was ours now. Or, more precisely, mine.

What we needed was a Confluence space that—unlike the current installation—was:

• Usable by people inside and outside of the team
• Structured to reflect our (new! evolving!) organizational design
• Tailored to users who browse and ones who search
• Populated with relevant content

Like Mari Kondo, the popular organization consultant, I've been bringing order to our informational hoarding house since autumn. In this talk, I'll discuss the information architecture thinking behind every step of the process. Not just what I did, but why, what user needs I was serving, and how. I'll discuss the clever (and not-so-clever) things we did, and explain what's left to do and what challenges I anticipate there.

Hatshepsut, the second historically-confirmed female pharaoh of Ancient Egypt, was a great leader and innovator of her time, which we’ve all learned about through hieroglyphic-laden documentation. She’s also a victim of changes to documentation in an effort to erase her contribution to the kingdom’s feats. Luckily for historians, edits to stone are hard to conceal!

Often, the factors that are overlooked when writing project documentation are the historical conditions surrounding adoption and advocacy of a particular solution. Freshly hired software engineers at Relatively Sized Tech Company may have made choices based on the lack of information explaining tech stack history and the decision-making that frames it.

As an Egyptology-Major-turned-Engineering-Leader, I’m surprised by how little historical evidence is referenced when it comes to technical decisions, until I discovered the main cause: Documented context rarely exists. Oral tradition often reigns supreme. As technologists and writers, we should lead the change we want to see in robust, well-executed documentation.

In this talk, I’ll walk through some useful ways to ensure historical context is well-documented for your project, and why doing so at the project’s inception and throughout its maintenance is particularly important:

– Learning from archaeology to understand the human activity involved in technical projects

– When and how to document this activity, including decisions, discussions, and defeat

– Why timing matters and how changes after-the-fact can be harmful for future users and contributors

By applying an archaeological mindset to documentation, we can avoid the frustration that a lack of historical context affords, particularly when a team member leaves or a new pharaoh begins their reign. Let us all be diligent archaeologists and make the excavation of documentation a breeze for those who come after us.

Writing documentation is great. Writing with the intent to make your content easily discoverable is better. Search engine crawlers are users that parse your content to show it to humans. Let's look at the little things you can do to make your content bot-friendly.

If you shout "OK Google", Google will shout facts back at you. Visual and voice search mean that your content may not be consumed in its original format. Want to know more about making sure your content travels well? This is the talk for you!

We'll discuss wonderful topics : - search intent - search experience - meta titles & descriptions - content hierarchy - B.E.R.T. (machine learning used to improve Google search results) - voice and visual search

...but also provide tangible tips that you can integrate in your writing process.

For years, I have been sailing around the submerged iceberg of Pattern Languages in my careers of software developer, technical author, information architect and Scrum Master. I eventually landed on Christopher Alexander’s book, “A Pattern Language” as a recommendation from my Design Thinking professor while studying a master’s degree. Once I started to explore, I found connections everywhere. Interestingly, pattern languages provide a unifying link between all my careers. Pattern languages have had a transformative effect on numerous domains: built architecture, information architecture, software design patterns, wikis, Scrum and Agile to name a few. Yet for such an influential approach, pattern languages remain surprisingly hidden. I share my journey of discovery and rediscovery of language patterns. I will cover a brief history of pattern languages and their impact on multiple domains. This gives a context for my attempt to use pattern languages to link interests from my various careers. This is primarily through the medium of a wiki which is a direct descendent of the original explorations of pattern languages. Finally, this is an opportunity to share resources that I have found useful on my journey. The aim is to leave everyone with signposts to pattern languages in multiple domains. Hopefully everyone will leave with some stimulating ideas about how pattern languages may impact their own career.

Videos, GIFs, and screenshots are brilliant additions to your help docs - enabling customers to understand a product feature quickly and painlessly - but how do you keep those videos (and other visuals) current when your UI changes frequently? ... by making your process modular, measured, detailed, and elastic.

• Modular: When you save editable pieces of your videos and GIFs (your assets), they can take minutes to update, not hours. We'll go over the pieces of the files that you want to keep separately, and how to utilize those pieces to update an asset quickly.
• Measured: How many screenshots of your app can one staff member update in one hour? How many screenshots do you have? How many are affected by next month's feature release? Knowing these numbers, tracking them over time, and having them available to report to senior leadership means that you can know exactly how much staffing you need to be ready for a UI update.
• Detailed: Meticulously record every detail of how you create your visuals. How do you decide how much of the app to include? What colors will you use? How does your intended audience affect your tone, pacing, and use of annotations? Having this all recorded will help others replicate your work.
• Elastic: You don't need 10 visual experts sitting around twiddling their thumbs waiting for an update, just so you'll be able to deploy them quickly for a UI change. But you also don't want 3 documentarians working around-the-clock the week before the release. What's the solution? Elastic staffing of your documentation team. We'll go over how to achieve this on your team.

Visual documentation can be tricky to pull off in an environment of quick UI changes, but making the effort to do it well pays off for your customer and your ticket volume.

Technical writers are not always required to write exclusively for engineers. Sometimes they also have to write for their bosses, their bosses' bosses, investors, buyers and end users. These readers may or may not come from technical background. In this talk we will look at ways you can ensure your message gets across.

Technology and process are invariably linked to the success of your product. In ABN AMRO, we are defining how documentation works for internal and external API products. We set up a new internal and external developer portal this year. This presentation describes ABN AMRO’s journey towards DocOps from the point of view of the company’s first dedicated Documentation Manager and Technical Writer.

The following topics will be covered: - Requirements gathering - Tooling selection - Defining processes and establishing a way of working - Defining and creating resources - Providing technical writing training, coaching, and support to authors - Content management

We're a couple of Docs Geeks with a story about how our cross-functional team scratched out a wholistic technical content strategy. With few resources, but a lot of curiosity, enthusiasm, and scrappiness, we've seen some pretty awesome results.

We'll cover the ways we identified problems with technical content in our organization, defined and implemented a strategy to improve it, celebrated successes along the way, and how we're now keeping up momentum as new challenges arise.

We'll talk about our principles, to inspire others looking for change:

− Be social - Create your vision & strategy as a team

− Be loud - Tell your story to influencers and other teams

− Be scrappy - Prove your value and defend your vision

− Be curious - Take on new technology and approaches

− Be avante-garde guinea pigs - Dream big and try everything!

End users, sales engineers, and developers are united in their criticism of your documentation:

It doesn't have enough examples!

What can you do? Even if you have the time to provide examples, you might feel like you're not qualified to write them. Your audience asks for examples, but they don't give you any specifics. Your engineers provide examples, but your customers can't understand them.

In this talk, I'll prove that your technical writing skills make you well-suited to writing effective examples. I have more than 20 years' experience writing API examples for companies such as Oracle, Google, and Splunk, and I've learned that good examples depend more on writing skills than coding skills. Based on this knowledge, I'll show you how to:

• Determine which examples you'll need
• Provide examples with the right amount of complexity
• Work with SMEs to develop examples
• Create style guides for writing examples
• Store examples as live code and refer to them in documentation

While lecture style teaching barely has to be adapted when it moves online, the story is different for student centered, interactive formats that teach practical skills, like we do in our programming trainings. Compared to what we are used to in a classroom, the different channels of communication are limited in online platforms. A few examples: Nonverbal communication is extremely reduced. Informal communication between participants, used to clarify on assignments or information is much harder. If students are split up in groups to work on assignments, there often is no channel to deliver additional information to all groups at once. The fact that the participants of our embedded trainings have to interact with microcontrollers brings further challenges: assisting students with debugging hardware can only be done verbally as we have no possibility to physically check student's hardware, if needed.

When we had to move our face-to-face trainings online because of the corona virus crisis, this is how we addressed the lack of personal interaction in the design of our material:

• We provided a walkthrough with
  • explicitly phrased tasks
  • expected outputs
  • troubleshooting pages
  • problem solving strategies and tiered aids
  • answers to expected questions
  • additional explanations
• To structure this huge amount of information we
  • used a book structure with chapters
  • visually marked different kinds of information (action items, more details, etc)
  • separated assignments from solving strategies
• We debugged our docs continuously before deployment by
  • letting target audience work through the material, using different setups to be able to anticipate as many problems as possible
  • integrating what we learned into the material
  • repeating this process

A great while ago, when the world was full of wonders, technical writers just described the systems that we were documenting. Sometimes, we got adventurous and wrote laundry lists of procedures. These early practices led to the phrase RTFM (Read the F____ Manual), because NO ONE ever didl, even if the answer was there. We didn’t think much about what our customers wanted or the user stories that they live by.

But any folklorist or linguist can tell you that narrative is the basic structure of reality--whether those stories are fairy tales, Biblical parables, or the instructions that teach a systems administrator how to install a virtual machine.

In the 1800s folktale collectors tramped across Europe, Asia, and the United States recording the stories that people told around the fire and in their homes. These early folklorists quickly discovered that these stories follow set structures and have archetypal characters.

Technical documentation also has fixed structures and archetypal characters. But instead of talking about scullery maids and third sons, technical writers compose stories where the heroes are customers, developers, and systems administrators.

The Russian folklorist Vladimir Propp decomposed all of Russian folktales into 31 “narratemes” or story elements. Similarly at Red Hat, we divided all of our documentation into two role-based life cycles: one for developers and one for administrators, with fixed tasks for each role. Sure, there are still a few tasks and concepts that can fall outside these standard structures, just like there are some fairy tales that are unique. But the vast majority of our user stories and epics fit within these narratemes.

In this talk I’ll introduce the audience to tale types and folktale motifs and show how similar these are to Red Hat’s standard life-cycle components. I’ll show diagrams that content strategists created at Red Hat to show product life cycles and real examples of content that fits within these standard categories. I’ll help you listen and find the story of the people for whom you’re writing.

So that we may all live happily ever after.