This chapter is from the book
This chapter is from the book
This chapter is from the book
Topic-Based Writing Checklist
|
Guideline |
Description |
|
Check that each topic contains only one type of information. |
Use the different topic types in DITA to separate task, conceptual, and reference information. |
|
Check that each topic is self-contained. |
Eliminate text that points to other topics (other than the occasional cross-reference), text that points to sections in the topic, such as "The next section describes table spaces," or topics that serve merely to glue other topics together. |
|
Check that topics don't cover too much information. |
For example, writing one topic to describe even a single commercial aircraft model is too much information for one topic. Instead, break up the topic into more concept topics and subtopics, such as "Engines," "Passenger seating," "Pilot console," and "Electrical systems." |
|
Ensure that your content is task oriented. |
Task orientation means that your content focuses on real user goals, not product functions or features. Don't focus on pseudo-tasks such as "Using the email feature." Using something isn't a real-world goal. "Sending a document through email" is a real goal. |
|
Do a task analysis to decide what information your topics should contain. |
Technical information is effective only if it answers users' questions quickly and completely. Ensure that you understand the level of expertise of your users and their goals. |
|
Follow minimalist guidelines. |
|