Documentation Team »

Topic Types

This page is being used to plan common topic types for Mallard documents. When we've fleshed out recommendations, this page should be moved under Contributing.

Task

Task topics describe how to accomplish something the user is interested in doing. Do not confuse menu items or buttons for tasks. If there is a button to frobnicate a file, it doesn't necessarily mean that frobnicating files is an interesting task. Ask yourself what users might be trying to accomplish that would require them to frobnicate a file.

Concept

Tip

Tutorial

Tutorial topics provide detailed instructions on how to do something interesting. Tutorials are generally longer than tasks. Tutorials aren't intended to show users exactly what they're trying to do. Instead, they show users how to do something, teaching them in the process.

For example, you might write a tutorial about how to draw a smiley face in Inkscape. Users probably don't care about how to draw a smiley face, but by following the tutorial, they will learn how to use Inkscape better.

Solution

Solution topics provide solutions or work-arounds to common problems.

Screen

Screen topics provide a reference for what the user is seeing. Be careful not to focus your document around screen topics. Generally, we don't want users browsing to screen topics when they click around from the root page. Instead, users will be brought to a screen topic when clicking the Help button in something like a Preferences dialog.

It's usually not possible to direct the user to a single task from most dialogs. So we instead direct them to a screen topic. Screen topics should briefly describe the options the user is seeing. If there is anything that may require a lengthy description, link to a concept topic that discusses it.

Ask yourself why users would be looking at this window and assemble a list of tasks they might be trying to perform. Crosslink to as many tasks as makes sense. Treat screen topics almost as if they were guide pages.