With or without text (chapters), that is the question!

[brunos]

This is about whether it makes sense to use "Chapter without text" when dealing with single-source documentation. All opinions are welcome.
--------
Back in the Winhelp-only era, all the chapters were without text by design - no choice, no doubts! If you needed an introduction (as in a chapter with a series of procedures), you wrote an introductory topic - and that was it. Such topic was useful also to provide an entry point to the chapter - otherwise, the readers would jump into the first procedure, without any preparation.

Then, the CHM format brought "Chapters with text". It meant you can move all your introductory topics to chapters (high price - a lot of clicks was required to do it in huge projects).

But, there are chapter which do not need introductions; or the chapters which do need long introductions, not suitable to fit into a chapter topic.

Alternatives:
1. Write a trivial placeholder for the chapter with text, such as "This section helps with assigning, sending, and closing text." (Microsoft style).
2. Forget it, and just use Chapter without text.

But! HTML help viewer has an unpleasant behavior when you click a Chapter without text, if previously there was a topic displayed. Actually, nothing happens. The previous topic remains displayed. The reader may believe that either computer or mouse are broken (as they don't react on clicks...)

That was the primary reason I decided to ban "Chapters without text" from my files. Was it an over-reacting?

Regards,
Bruno

[TomHenehan]

I recently ran into a problem related to the question of whether or not to include text in chapter-intro topics:

Because I'm so new to writing online help (as opposed to print-manual-only documentation), I was not aware of the historical fact that help files were originally organized with chapters without text. (I probably should have noticed this as a *reader* of WinHelp, but never did.)

In any event, in my first H&M projects, I have consistently included introductory text in all my chapter-heading topics (just as I had always done in print-only format).

This came back to haunt me when I lost a project and was unable to repair/recover my .hm3 file. I had a fairly current .pdf version of the project, and imported it into H&M to create a "new" project -- actually, a duplicate of the lost project.

The newly created file included chapter headings WITHOUT text, adding an extra level to my outline form. Most of the project consisted of two levels only (chapter-intro topics & subtopics), which was fairly easy to reconfigure.

I had one chapter that included a third level ("sub-sub-topics") -- the results of importing the .pdf back into H&M were more seriously screwed up in that chapter.

I hestitate to suggest that H&M should have recognized the original hierarchical structure of the imported acrobat file -- who knows how complicated it might be (if not impossible) to analyze the structure of every different type of file that might be imported? Rather, I am offering a cautionary tale about the unforseen dangers of straying from a set of default standards when creating new work...

[Olivier Beltrami]

But! HTML help viewer has an unpleasant behavior when you click a Chapter without text, if previously there was a topic displayed. Actually, nothing happens. The previous topic remains displayed. The reader may believe that either computer or mouse are broken (as they don't react on clicks...)

That was the primary reason I decided to ban "Chapters without text" from my files. Was it an over-reacting?

That's exactly why I am also using chapters with text.

[John Smith]

I always use chapters with text, plus whatever text I have there I always copy to an Overview page directly underneath. The chapter gets All Builds,

The overview only gets to build for winhelp. That way whatever format you are always covered.

[Roberts]

This is a good idea. But for the Chapter, you need to mark all the builds except Winhelp, right? Otherwise, you'll get a duplicated chapter topic in the Winhelp compile.

On second thought, if you do that you won't get any of the subtopics in the HLP. So, how do you keep from getting the duplicated chapter topic using this method?

[John Smith]

For the chapter build you mark it for all builds - it just won't build when you build a winhelp (You may get an error in the build, but it just advises you that it can not convert to winhelp and it will be blank)

For the overview page, mark that for winhelp build only.

If you did want to avoid the error (which makes no difference anyway), you could mark all topis underneath, winhelp build, after turning it off in the chapter.

I haven't got around to this yet, but am going to look at whether I can use a text variable in the overview, linked to the chapter, so I only have to maintain text in one place.

There is alo one other problem with this solution. Help Context number can not be the same for both.

The reason I haven't looked to hard at the above two items, is I do not know any of our customers who will not be able to read a chm file, so we have gone that way.

[John Smith]

And here is the answer to the two problems above.

Just read a thread by Tim

http://helpman.it-authoring.com/viewtopic.php?t=469

You can duplicate a topic, and when you edit one, the other will be updated. Both contain the same help context number, but you can change the build to be different for both.

Although topic ID needs to be the same, the TOC name can be different. You can change the heading but it will be reflected within both.

Example:
Toc
Chapter: Properties and how to.
Topic: Overview of changing properties

Heading on text for both
How to change properties in your application

[John Smith]

ahh well a bit to good to be true

In my example above

Example:
Toc
Chapter: Properties and how to.
Topic: Overview of changing properties

Although H&M allows you to change the TOC, when it builds the winhelp 2 file, it ignores what you have typed and you get the following -

Chapter: Properties and how to.
Topic: Properties and how to

In other words the second instance will take the on the TOC description, not what you have typed.

real life example - In my file I have a chapter called Introduction, and a second instance of the chapter, but as a topic. In the TOC I call the second instance Welcome (topic ID stays the same to maintain connection to the original). When I build the winhelp 2 file I get a chapter clled Introduction, and then a topic called Introduction.

Works if you do not care about the same name for each chapter being following with a topic of the same name. Going to stick with my chm files.

[Tim Green]

If you use this method you can't have any differences in the two instances. The reason for this is that all you are really creating is two references to the same topic. Since there's only one topic, any changes you make to it will be there no matter which road you walk down to reach it...