How to Structure a Help Project, Part 2

Blogs

In Part 1 of How to Structure a Help Project, I discussed the 5 steps to structuring a Help project — specifically, how to gather and organize the topics for a Help system. Now we’ll dig into how to structure topics themselves, which is just as important.

I suggest developing and using topic types, because they:

Eliminate redundancy
Prevent accidental omission of information
Encourage writing consistency
Work with either writing paradigm (Book or Topic)

Following are three example topic types, but you can create whatever you need, or adopt a set of predefined topic types.

UI Overview Topic Type

This topic type introduces each section of the user interface.

Information requirements:

Breadcrumbs (automatically generated by Doc-To-Help)
Topic Title
Image
Conceptual overview
Additional reference information
Related Topics (automatically generated by Doc-To-Help)

Note that the topics in the “Related Topics” list appear in the Table of Contents.

Functionality Intro Topic Type

This topic type introduces a piece of functionality, and leads to more information.

Information requirements:

Topic Title
Answer the question: “Why is this important?”
Overview
“How to”/Tasks
Video (if available)
Related Topics (automatically generated by Doc-To-Help & you can add additional)

Dialog Box Topic Type

The context-sensitive Help for dialog boxes needs to stand alone, and this topic type accounts for that.

Information requirements:

Breadcrumbs (automatically generated by Doc-To-Help)
Topic Title
Answer the question: “Why do I need this dialog box?”
Optional: Important Fact
“How to get here” (this topic may be accessed independently of dialog box — users need to know how to open the dialog box.)
Task(s)
Dialog Box definitions
Related Topics (automatically generated by Doc-To-Help & you can add additional)

Now Go Forth and …

Develop your own topic types, adopt a predefined set, or adapt the ones above for your needs (the topic types above are a subset of those used in the Doc-To-Help project).

In addition to all of the other benefits of using topic types, you will also find that you can produce content much faster, because you know exactly what you need to research and include.