Topic Types

Jan 6, 2012   //   by Barry Saiff   //   Blog, Concepts and Definitions, Reference Articles  //  No Comments

Hang on!  Before reading further, we just wanted you to know that this post is related to the previous.

Task Topics contain a procedure, represented by a list of numbered steps. The title of a task topic names the task. After the title, a few introductory sentences introduce the procedure by answering questions such as:

  • Why should I perform this task?
  • What do I need to do before performing this task?
  • What can I do after performing this task?
  • What problems might occur if I perform this task?

After the introductory material, a one-line lead-in introduces the procedure. A list of numbered steps follows. Each number is followed by only one sentence, which instructs the user to do something. Any additional material needed for that task is provided in a separate, indented paragraph under the numbered step. Some of these paragraphs can be links to other topics.

Here is an example of a task topic that explains how to write a task topic:

[Title] Writing a task topic

[Introduction]A task topic includes a procedure, consisting of a numbered list of steps. A limited amount of introductory material precedes the procedure. The procedure itself provides only the information essential for performing the task. In some cases, you can provide a link to relevant information, instead of cluttering up the procedure with reference or conceptual information.

[Lead-in] How to write a task topic:

  1. Write a title for the topic that includes a gerund (a word ending in “ing”), and describes the task documented.
  2. Write an introduction for the topic that explains the context of the task.  Mention any restrictions on performing the task.
  3. Write a lead-in sentence that begins with “How to” and matches the title.  End the lead-in sentence with a colon. The lead-in sentence is usually not a complete sentence (see example above).
  4. Write the numbered steps for the procedure.

The first paragraph of a numbered step contains only one sentence. That sentence instructs the reader to do something. Additional information is provided in separate paragraphs indented below the numbered paragraph. Keep the additional information minimal.

By not mixing, for example, task and concept information in the same topic, you gain several advantages:

  • A reader who just wants to know how to do a task does not need to wade through conceptual information to find the procedure she needs.
  • If you choose to present all the procedures together in a special document, you don’t need to separate out conceptual information.
  • You can easily provide all the task topics to the team that will test the procedural documentation.
  • By including links to the most relevant concept and reference topics in each task topic, you can direct the reader who is interested to useful information without cluttering up the procedure for the reader who doesn’t need that information.

Reference Topics contain reference material. Reference material may be necessary to perform tasks or to understand technology. Reference topics often contain tables of information. For example, lists of parameters and their corresponding values or impacts. A table of types of mortgages and the requirements for each type. A table of features, showing which features are available from the product’s graphical user interface (GUI), and which features are available from the command line interface.

Concept Topics provide background and explanation. Even if it is necessary for the reader to understand quite a bit of background information before performing a task, do not include all of the information in the task topic. Instead, include a link to one or more concept topics that provide the necessary background. For example, an explanation of each type of mortgage and its history belongs in a concept topic, not in the midst of a procedure for choosing the mortgage type.

Process Topics describe complex processes that consist of multiple tasks, each of which consists of multiple steps. A process topic typically contains a table. Each row in the table represents one task, and provides a link to that task topic.

Process topics can document any of the three basic types of processes:

  • Linear. In a linear process, a set number of tasks must be performed in a specific order, without variation.
  • Branching. A branching process contains one or more decision points. At each decision point the reader can choose from two or more “branches” or alternate paths through the process.
  • Circular. After completing a circular process, the user can continue to perform the same tasks again. Some circular processes can be started at any point in the circle.

The process topic shows the sequence of steps, and indicates any decision points where the sequence may branch, or become circular. A process topic may contain a flow diagram, that documents the process flow. Flow diagrams can be particularly useful for branching and circular processes.

Online Help Topics typically contain a table that lists controls, commands, or features of an interface or product. These topics are accessible from within the product interface. If the topic contains information specific to the interface location from which it is accessed, it is called a context-sensitive topic.

Context-sensitive help topics often list all the controls available on a specific page or screen of the user interface, documenting each control, and provide links to relevant task, concept, and reference topics. Depending on your content strategy, you may choose to also provide procedures in the online help topics themselves, rather than linking to task topics.

Leave a comment

Saiff Solutions In The Media

- TechWhirl
- Nominated for 2015 Rice Bowl Asean Start Up

Click image to enlarge

Testimonials

“After Symantec acquired Brightmail in 2004, Barry played key roles in integrating the information development team and their content into Symantec’s then-developing Unified Content Strategy. Barry [Saiff]’s experience, product and content knowledge, and leadership qualities helped the Brightmail team to become a trailblazer within the company. The processes, tools, and practices they helped to develop for content management are used throughout the company, thanks in large part to Barry’s participation in numerous cross-departmental teams. Barry is a natural leader who can effectively contribute to any endeavor. He has a passion for serving customers that drives him to create and evangelize process improvements and to collaborate effectively with diverse groups and individuals. I would be glad to work with Barry again.”

Alexia Idoura (nee Prendergast)
Senior Manager, Symantec
February 16, 2011

Read more testimonials here.