Best Practice For Starting a New Topic

[erinep23]

What do you think is the best practice when deciding to create a new topic, as opposed to just adding and adding to one topic? Assuming your target is a pdf, but you'd like to generate Web Help HTML5 down the line. I normally go with the "H1 or H2" Rule -- if a section needs either heading, then it's time to start a new topic. What's everyone else's thoughts on this?

[kwag_myers]

One rule I've heard is to never have more than three layers in the TOC of WebHelp. But I've run into situations where that just wasn't practical. The thing to remember with web-based user guides is that most people just want an answer to a specific question, so you have to find a balance between too many clicks (to find the topic) and topics that are too long.

Most of the projects I've worked on have had the requirement of following the UI. For example: Each tab of the Home page is a topic, and each dialog of each tab is a child topic of the tab, etc.

[erinep23]

Oh, I like that answer. Thank you.

[ccardimon]

I like that answer, too. Thanks!

[SteveS]

There is an argument for a topic to have only enough content to fill one screen on the viewing device with a next button (hyperlink) going to the next topic...

[wclass]

...
Most of the projects I've worked on have had the requirement of following the UI. For example: Each tab of the Home page is a topic, and each dialog of each tab is a child topic of the tab, etc.

I've done this in the past, and it works for reference material, but for introductory material and training, I am trying to create topics based on tasks or activities that people need to do. Sometimes a major activity can cross more than one UI tab.

[ccardimon]

There is an argument for a topic to have only enough content to fill one screen on the viewing device with a next button (hyperlink) going to the next topic...

Sadly, hyperlinks are of little value in PDF output.

[erinep23]

Sadly, hyperlinks are of little value in PDF output.

True, but let's be honest - most people don't print pdfs out anymore (trees sigh in relief). They just look at it online. My issue with hyperlinks in pdfs are that they are butt-a** ugly.

[RamonS]

...
Most of the projects I've worked on have had the requirement of following the UI. For example: Each tab of the Home page is a topic, and each dialog of each tab is a child topic of the tab, etc.

I've done this in the past, and it works for reference material, but for introductory material and training, I am trying to create topics based on tasks or activities that people need to do. Sometimes a major activity can cross more than one UI tab.

That is why using the DITA information typing might come to the rescue here. Split the information into concept (general info, introductions), task (step by step instructions), and reference (anything else, mainly detailed description of a feature, UI control, error message). The add vs new decision should be based on what topic type it is. If there are three more steps for a task then of course you add that to the existing topic, but the description of the UI controls that were added to the workflow each requires its own new topic. Insisting on a one size fits all rule doesn't work.

[ccardimon]

My issue with hyperlinks in pdfs are that they are butt-a** ugly.

True, but that's what I'm asked to deliver.

[kwag_myers]

...
Most of the projects I've worked on have had the requirement of following the UI. For example: Each tab of the Home page is a topic, and each dialog of each tab is a child topic of the tab, etc.

I've done this in the past, and it works for reference material, but for introductory material and training, I am trying to create topics based on tasks or activities that people need to do. Sometimes a major activity can cross more than one UI tab.

With this approach, you need to work with someone who has direct contact with users and can tell you what those tasks are. If your company has a Help Desk of any form, maybe you can survey them for FAQs.

I currently have one project that is set up this way with several topics that are a mile long, which goes against all my DITA training. I use Drop-down text for nearly everything but an introductory sentence/paragraph, similar to Flare Help. Each topic contains the concept, reference, and tasks associated with a specific object which the product produces. For example: This product allows developers to build various types of charts and graphs, which are then put into a single page for viewers. Each type of chart/graph has a single topic.