Bill Hackos, Comtech Services, Inc.

DITA is the “in” thing these days. Everyone wants to move to DITA. Our DITA workshops and our five-day DITA Boot Camps are packed. But information developers seem to have forgotten management. Moving to DITA requires even more management than traditional information development.

Some frequently asked questions are: Should concepts come before tasks? What about reference material? Our answer is: It depends. Remember the two points of view, the author and the end user. Let’s consider these points of view separately.

Author’s viewpoint

This one is easy and has a specific answer. If you as an author are creating a user’s manual, you will have a set of tasks to author. If you don’t, then you are not writing a user’s manual. You know the end user wants to use the user’s guide primarily to learn how to perform tasks. So, as an author you want to keep your writing action-oriented. The only way to do this is to create tasks first, then creating concept and reference topics only as needed by the user to perform specific tasks. Each concept or reference topic must be associated with a task, although concept and reference topics may be associated with more than one task in a reuse situation. As an author, you should never create an orphan concept or reference topic. Orphan concept or reference topics have no value to an end user no matter how clever they are.

You should author your tasks before authoring any associated concept or reference, and then only if there is a clear need for the concept or reference in performing the task.

End-user’s viewpoint

The order of topics in the published user-centered manual may not have any relationship to the order of authoring described above. The only way to determine the optimum ordering and even the need for a particular concept, task, or reference topic is by understanding how the user does his job using your product and how he/she uses the documentation you provide.

Understanding the user does not come naturally to your authors and information architects. You really need to visit users and talk to them about how they do their jobs. At Comtech, we are frequently asked to do user studies for our clients. We always find some significant information about users that affects the way our clients design their manuals. We also usually find that a variety of users with different skills and experience use the product. The variety of users must also be taken into account in the design.

It is possible that the user may need the concept before the associated task. Experienced users may skip the conceptual information, or you may provide separate manuals for different users. The same goes for reference information. Sometimes it’s most useful before an associated task and sometimes it is most useful after an associated task.

The need to manage

The examples above illustrate the need to manage topic-based writing projects, whether they are in DITA, Information Mapping, or Docbook. These tools provide little guidance about the authoring process or the end-user design. Managers cannot delegate the authoring and design to their tools.