In my last post (How do you like to write?) I discussed how Doc-To-Help makes it simple for you to write a book, chapter by chapter  — and still output high-quality, feature-rich, *logical* Help and web output, as well as attractive manual output. In this post; a few writing tips... 

If you follow certain guidelines when you are writing, the online output generated from your Word Documents will be logical and consistent, while not compromising your writing flow.

If you are writing software documentation, standardize on a consistent heading (such as “Using the… Screen”) which makes sense in both the book and help. Since your heading will become a topic in online outputs, also design a consistent structure for each topic that you will later map to Help buttons*. For example:

  • Title 
  • Introduction
  • How to access the screen/dialog
  • Task(s)

Be sure to cover all the main points in under one heading, so that that a single topic will work for each dialog box.

  • Standardize on one (at most two) Heading styles that Help button topics will map to. It can be confusing to the user if multiple styles appear from Help buttons.
  • Never use the word “chapter” or any other word specific to books. (For example, “page” “topic” “help system” “manual”) “Section” is a good substitute.
  • Use “See *Insert Link*” rather than “See below,” “See above,” etc.

* This mapping is done using context IDs. See Implementing Context Sensitive Help.

Next time ... The Doc-To-Help toolbar in Word.