MadCap Software Forums

Hi

I am wondering about how to approach the logical problem of having a single level 1 heading followed by several level 2 headings with their associated topic text.
Do I put H1 in a topic of its own, or should I always add text under H1 to make it a complete topic?
---
H1
---
H2
topic
---
H2
topic
---
H2
topic

I may not be following entirely, but why would you put only a heading into a topic?
I see it working as such:
H1
(text)
H2
text
H2
text
H2
text

There may or may not be text between H1 and the first occurrence of H2, that depends on context. BUT, all of this is within one topic. If you want to split the content into different topics (files) then use H1 for each of them or include the H1 heading in the topic with the logically first H2 heading.

It also depends a bit on the output you are aiming for. Do I suspect right that you are going for print output / PDF?

I have lots of topics with just a level 1 heading. I single-source WebHelp and PDF, and these end up being the book topics in the WebHelp TOC that you click on to show the list of topics in that book. In the PDF, they are just the chapter headings.

I am tending to move away from lots of very small topics, to fewer larger ones (perhaps with drop-downs for WebHelp). So if the whole thing is only a few pages, now, I would probably opt for a single topic, with the H1 followed by all the H2s.

But if the whole thing is longer, or if you have good reasons for wanting separate topics (reusability, for example) keep the separate topics, and have a separate H1 topic with just the heading, and, if applicable, as Ramon says, any paragraph text at that level. Then add the level 2 topics to the TOC, indented below the heading topic.

I wouldn't ever put the H1 in with the first H2 topic. You will be sacrificing reusability, hiding the structure from others and making a maintenance headache. What if someone later on adds a new level 2 topic before your current first level 2? They may not realise there's a level 1 heading lurking in that topic. I prefer to make sure the TOC reflects the structure of the content, and then I can use the "Use TOC depth for heading level" feature, which makes life easier in other ways too. If you use that feature in your PDF target, all your topics can start with H1, and the PDF output takes the heading levels from the TOC structure.

I single source my WebHelp and PDF User Guide, so I've tried to come up with a topic structure that works for both. Even if you think you only need one type of output now, it may be better to keep your options open if possible.

Hi The_docman,
Looks a bit like the H1 in your example is a chapter name. These kind of headings I tend to put into the label of an unlinked book and when creating PDF, I check the option "Inject headings for unlinked books in TOC". That setting is in the target on the Advanced tab. For online output, the label will appear anyway in the output TOC.
Regards,
Lydia.

Thanks All

Msquared wrote:I have lots of topics with just a level 1 heading. I single-source WebHelp and PDF, and these end up being the book topics in the WebHelp TOC that you click on to show the list of topics in that book. In the PDF, they are just the chapter headings.

I can see the point for this when going to PDF, but forWebHelp? When clicking on a book it shows the associated topic and that has only a heading? As a use I'd wonder what is missing there. These topics are great for providing some general information about the functional area or feature described in that section. There does not need to be much content, but there should be some. Just my 2 cents...

RamonS wrote:

Msquared wrote:I have lots of topics with just a level 1 heading. I single-source WebHelp and PDF, and these end up being the book topics in the WebHelp TOC that you click on to show the list of topics in that book. In the PDF, they are just the chapter headings.

I can see the point for this when going to PDF, but forWebHelp? When clicking on a book it shows the associated topic and that has only a heading? As a use I'd wonder what is missing there. These topics are great for providing some general information about the functional area or feature described in that section. There does not need to be much content, but there should be some. Just my 2 cents...

I would tend to agree with Ramon. This is a perfect place for a miniTOC, in fact.