Delivering Documents For All Three Use Cases

Users end up with documentation for three different reasons. Some users are new to the product and want to read everything so they can develop a comprehensive knowledge of your software. Some users know how to use the product. They want to brush up on a task they only need occasionally or to learn a new part of the product. Most users come with a specific goal in mind and want to move on with their day having read as little of your documentation as possible.

Each type of user needs different modes of interaction, but you often have to serve them all with one. This talk addresses the different needs of each user archetype and how to meet the relevant needs in every document.

Conversational UIs for writers

Developers of voice and chat assistants are crying out for good writers to help them create the conversational interfaces of the present and future. In this talk, I will introduce what constitutes a 'good' conversational experience and how we, as writers, can benefit from this trend.

This will include advice on tone, variety of language, setting and checking user context, testing interfaces, presenting choice and much more.

How I decided to do this talk (Gap analysis and pull-apart documentation planning)

Figuring out what to write and how to write it can be tricky. In this talk, I lead you through the process that I use in order to figure out what needs writing, in what order, to provide my audience with the best experience and value, no matter the subject area. The talk covers practical aspects of reviewing briefs and specifications, audience and competitor research, and determining and prioritising value when you structure and write your documentation..

Writing extensions in Sphinx: supercharge your docs

Sphinx is an open source documentation platform. It provides an easy way to generate documentation to multiple formats (html, manpage, text, pdf, ...) out of a single set of reStructuredText sources. It has great inbuilt support for documenting software projects, but can be used for anything.

One of its strengths is its capacity for custom extensions, allowing you to add functionality to meet the particular needs of your project.

Come for a tutorial of the extensions mechanism in Sphinx. Learn how to generate a Google sitemap dynamically; and how to embed a "last updated" timestamp in your documentation, based on the time it was modified in version control.

Basic familiarity with programming is helpful, but you do not need to be a programming wizard to understand this talk.

Peanuts and Minimalism and Technical Writing

Well-written documentation is what we should all be striving for. Recently, Red Hat has focused specifically on quality. I took the job of constructing a team to learn about minimalism and how it can help us in technical communication.

Throughout this, I found the key to understanding minimalism to be comic strips. Learning to properly document a procedure is similar to telling a story in four panels and the tenets of minimalism are similar to those of a Peanuts strip.

These findings have helped create a standard that the technical writers at Red Hat can now easily follow, using learning modules, crowdsourced review seminars, and even stickers and posters