In my last post, I explained why FAQs are not the best means of helping users and site visitors find information. I suggested that you extract the key words from FAQs and transform them into topics. I introduced three common topic types: concept, task, and reference.
In this post, I will give tips and examples for writing each of the three topic types. My examples apply to a general business context and are somewhat simplified. If you are a technical writer, your topics will often be more complex.
Write a conceptual topic when you need to give an overview of a subject. To plan your content, ask yourself what readers need to know.
Suggestions for a Conceptual Topic
- Since a concept is descriptive, start the topic title with About.
- Introduce the concept and provide an explanation.
- Give an example to reinforce understanding.
- (Optional) Give a non-example if necessary to clear up any possible misunderstanding or confusion.
- (Optional) Use analogies, synonyms, or illustrations if you believe they will reinforce understanding.
911 is the telephone number to call when you find yourself in a life-threatening, emergency situation. You can call 911 using a landline, mobile, or pay telephone.
When to Call 911
Call 911 to report any of the following situations:
- Medical emergencies for which an ambulance is needed
- Crime situations requiring onsite police response:
- All serious, violent crimes, including homicide, robbery, sexual assault, domestic violence, and assault—even if the crime is no longer in progress or the offender has left the scene
- Home and business intruders
- Vehicle crashes involving personal injury, major property damage, or traffic tie-ups
- Sighting of a criminal whom you know is wanted by the police
Note: If you need to request city services or non-emergency police help, do not call 911. Call 311 instead.
Write a task topic type when you need to explain how to perform a procedure step by step.
Suggestions for Task-Based Information
- In case a reader doesn’t have the necessary background knowledge to perform a task, provide a link to pertinent conceptual information at the beginning of the task topic.
- Precede the numbered steps with an introductory statement.
Example: To create a widget, follow these steps:
- Try to limit each step to one action unless the second action is as simple as “…then click OK.”
- Where necessary, include explanatory text or results. To keep steps relatively short, show the explanatory content in a separate, non-numbered paragraph below the step.
- If a step requires a decision and possible branching, use a table or bulleted list.
- Bold the name of UI elements that the user interacts with or clicks on.
Example: Select Widget Model A from the list.
How to Call 911
Prerequisite Information: If you are not familiar with 911, we recommend that you read About 911 before you complete this task.
To complete a 911 call, follow these steps:
- Dial 911 from a residential (landline), mobile, or pay telephone.
Note: If call volume is heavy when you call, you might hear a recording and be placed on hold. Do not hang up and call back! You may have more callers ahead of you in the waiting queue.
- Slowly and clearly explain your emergency situation to the call taker.
- When prompted, provide the information listed in Critical Information for 911 Callers.
- (Optional) Provide your phone number in case the police need to call you back for additional information.
Even if you prefer to remain anonymous, we encourage you to at least provide your phone number.
Write a reference topic to provide supporting information for completing a task or enhancing knowledge. Reference topics provide factual information that you would look up rather than memorize.
While reference topics usually have a brief introduction, the primary content is usually a table or list. A list of recipe ingredients is an example of reference information that supports the important task of cooking.
In the 911 example, we could create a reference topic that lists all of the incident information needed when calling 911. We would then link to the topic from step 3 in the task example.
Critical Information for 911 Callers
While the information we receive varies according to the type of incident, the following details are required and critical:
- Brief description of the crime
- Time of occurrence
- Exact location, including street and unit/apartment numbers, if applicable
- Extent of injuries or property damage, if any
- Description of any suspects, such as
- Height and Weight
- Hair color and style
- Facial hair
- Scars, marks, or tattoos
- Description of any weapons used
- Description of suspect vehicle, including
- Tag numbers (including jurisdiction), and whether there are temporary tags on the vehicle
- Direction of suspect flight: Street name, nearby alley
- Method of flight: On foot, bicycle, or motor vehicle
- Your phone number—especially if you are calling from a mobile phone—so that the police can call you back if they need additional information.
Again, these are simplified examples, but I hope they give you ideas about how you can transform your FAQs into topics. I also hope you will consider using a topic-based approach to structure and simplify your content.
As always, I welcome your comments.