Valerie's Tech Writer Garden

Topics

3 min read

Technical writers usually write and organize documentations as topics. A  topic is a block of documentation that helps users to accomplish a specific goal.

A topic sturcture makes it easier to create new content. Topics are reusable.

Types of topics:

Concept Topic

Concepts provide background that helps users understand a product, a task they need to perform, a process, or any other conceptual or descriptive information, see Concept Topics or Overview Pages.

Structure:

  • A title (advised to be phrased as a gerund)
  • One or more body paragraphs
  • Optional: One or more examples
  • Optional: Two or more subsections, marked by subheadings
  • Optional: A list of related topics

Examples:

Task Topic

Task topics answer “How do I?” questions, see Task Topics or How-to Articles / Tutorials. A task topic only contains a single procedure. It consists of multiple steps, where each step describes a single action or command. A step can also describe the step results.

Structure:

  • A title (advised to be phrased as imperative)
  • Context (information about why the user would complete this task in terms of goals, and not in terms of the software application, e.g.,“To complete {goal}, follow these steps.”
  • Two or more task steps in an ordered list
  • Optional: A brief description (between title and context statement)
  • Optional: Prerequisites (if a task has one or more prerequisites, list them before step 1 of the procedure)
  • Optional: The result of the task

Examples:

Reference Topic

Reference topics provide data that is looked up rather than memorized. Reference topics often use lists, tables and descriptions of commands in a programming language, see Reference Articles.

Structure:

  • A title (contains a qualifier and noun to distinguish between reference topics and tasks, e.g., Grafana CLI)
  • Introduction (explains what to expect from this topic)
  • Body paragraph (usually uses tables or lists to provide information)

Examples:

Note

API Documentation is usually a reference topic, but it has its own guidelines.

Troubleshooting Topic

Troubleshooting is a systematic approach to solving a problem. Troubleshooting can be one of three types:

  • Introductory
  • Task
  • Reference

Introductory Topic

This topic introduces the troubleshooting section of a page. Example:

## Troubleshooting
 
When working with <x feature>, you might encounter the following issues.

Troubleshooting Task

The title should be similar to a standard Task Topic, e.g., “Run debug tools” or “Verify syntax.”

Troubleshooting Reference

This topic includes the message. Example:

### The message or a description of it
 
You might get an error that states <error message>.
 
This issue occurs when...
 
The workaround is...

Note

Title of a Troubleshooting Reference topic:

  • State the type of message at the start of the title, e.g., Error:, Warning:
  • Include at least a partial output message (if the message is longer than 70 characters, include the text that’s most important, or describe the message)
  • Do not use links in the title.

If you do not put the full message in the title, include it in the body text.

Tip

  • Use “workaround” for temporary solutions and ""resolution"" and ""resolve” for permanent solutions
  • If multiple causes or solutions exist, use a table format
  • If you use the exact error message, style it as code

Graph View

Backlinks