The DITA Project #2 Just Say No: when reference topics distract
To describe what you can do, or what options are available, use a reference topic.
A good rule of thumb is that users tend to need, and prefer, step-by-step procedures in task topics to more general reference information.
As an an example, consider the case where a user can customize display of information in a window. You could provide one or more reference topics that describe available options for sorting, grouping and filtering. Or, more effectively, you would provide task topics for each procecure. Such as:
- Sort columns alphanumerically
- Group by columns
- Filter information so you only see what is applicable to you
- Save the view you have set up
You might want to insert the topics in your ditamap as child topics under a topichead or under a concept topic such as “Custom Controls for Your View”.
The urge to describe everything would be, in this case, counterproductive and decidely non-minimalist. Adding a reference topic here would create more content to update/maintain over time and add to your translation bill. So, resist the temptation to add more reference content. Often, when tempeted by a reference topic, Just Say No.
