Lukas Reußner - Hitchhiker's Guide to Documentation Tools and Processes

This is a summary of a talk given at Write the Docs Prague 2021.

Lukas lives in Berlin and works as a technical documentation engineer. He’s obsessed with Hitchhiker’s Guide to the Galaxy. 

The Hitchhiker’s Guide is a book in itself but also has a book within the book. This talk is intended to guide you through your documentation project and your search for tools. 

Vogons are described as one of the most unpleasant species in the galaxy, just like someone approaching you with a new documentation project with no existing tools. 

Lukas warns us not to panic. That’s good advice for anyone. 

Lukas looks at documentation requirement categories and tool categories. Categories are nice and keep your life organized. 

Documentation requirement categories are: 

• The first group is user groups which includes contributors (maybe technical writers), consumers (people who consume the documentation) and operators (people who take care of the documentation publishing process). 

• The second category includes content tasks: planning, editing, reviewing, and styling. 

• The third category includes findability (how users find content), discoverability (how users find features they have never heard of), and accessibility (how easy it is for users to access your documentation).

The  tool categories are: 

• Wikis

• Authoring systems

• Word processors

• Markup code toolchains

• Media editing tools

Content delivery platforms make our content available to our users, take the content from sources and publish it on a website. 

Tool examples

Here are some tool examples. 

• Wikis include Confluence, MediaWiki, Notion, Intercom and Zendesk. Wikis are defined as a hypertext publication edited and managed by its own audiences. It contains multiple pages and can be open to the public or limited to internal users.

• Authoring systems include Adobe FrameKarker, Madcap Flare, Oxygen, and Paligo. An authoring system is a program that has pre-programmed elements for the development of user information. 

• Word processors include Google Docs and Microsoft Word. They are used for composing, editing, formatting, and printing text documents.

• Markup code toolchains include docToolchain, Gatsby, Hugo, and MkDocs. They store the source files in a version control system, and publish the doc artifacts automatically. 

• Media editing tools include Adobe InDesign, Adobe Premiere, Affinity, and Snagit. They are used for post-production editing of images, videos, and so on.  

Quality Function Deployment

Lukas talks about how Quality Function Deployment (QFD) transforms the voice of the customer into characteristics for the documentation tool. The “house of quality” includes customer requirements, functional tool requirements, and customer requirements importance, the relationships between 1 and 2, the implied importance, and functional requirement relationships among functional tool requirements. 

How are documentation requirements linked with tool requirements? Lukas uses a spreadsheet to compare these different requirements and assign them a different rating. You can get an instant visual representation of the results without working through a pile of numbers. 

Information Development Cycle

Documentation processes have a lot of variation, but they are all part of the Information Development Cycle. At the start of the cycle, you investigate the topic that needs to be implemented. You need to create a plan from the information you’ve gathered. Then you create the first draft, ready to be reviewed by Subject Matter Experts, and then revise the draft using feedback from the review. Then you are ready to publish your documentation. The cycle repeats itself. This process works in Agile but also the Waterfall environment. 

To summarize: 

• Collect your user doc requirements

• Define documentation requirement categories

• Rate documentation requirements

• Collect functional tool requirements

• Rate the relationship between documentation and tool requirements

• Analyze results

• Test your doc process with potential tools

• If requirements are fulfilled, you can start creating user information 

Listen to the full talk here.