Controlling lists with Autonumbering vs. Complex Selectors

[Wendy F]

We are converting a very large document set from RoboHelp and FrameMaker into Flare, and are trying to keep our source easy to work with and as clean and simple as possible. We produce context-sensitive help (previously output as chms, with Flare we're upgrading to HTML5) as well as pdf documentation.

Our latest debate is about Autonumbering (using multiple classes to control the formatting of lists and items within lists such as images, tables and notes) vs. controlling the same with Complex Selectors.

Flare's own Help says the following:

Note: It is possible to use autonumbering in online outputs, but only in a limited way. For example, if you have notes throughout your project, you can create an autonumber format on a paragraph style class that simply has the text "Note:" followed by a space. Then whenever you want to apply that style class to note content, it will automatically start with "Note:" so that you don't have to type it each time. However, in the traditional sense where autonumbering is used to increment numbers for elements such as chapters, figures, and tables, it is really only intended for print-based outputs.

If autonumbering is intended for print outputs, does that mean that complex selectors do not work as well for print? Can anyone be more specific as to what the limitations of autonumbering are for online outputs?

Personally, I like the idea of controlling lists with complex selectors because I think I have the same capabilities with "cleaner" code, less mouse clicks, and less likelihood of operator error (choosing the wrong style), but I've got a department to convince.

Your opinions are greatly appreciated.

[ChoccieMuffin]

I love complex selectors. It sometimes happens that a list that is indented to a third level also needs to be somewhere else indented to a second level, and that's a cinch to do, as the code in the topic for that list is identical, and it's the CSS that controls how it's displayed.

I think one of the limitations of using nested (complex) lists is that you can't change the colour of the number of bullet. But frankly, I can live with that!

[BedfordWriter]

Very recently, there was an excellent webinar on this topic. You can download the slides from Madcap:
https://www.madcapsoftware.com/demos/si ... 9174614351

[Wendy F]

Thanks very much for the responses so far!

Yes, we saw the webinar live. It was very good, but it didn't do much to address why you would use one method over the other.

Hopefully, the community will continue to chime in with their opinions.

Cheers!
Wendy

[Daniel Ferguson]

Hi Wendy. I think you're going to have a hard time finding a definitive answer to this question. I've been in heated discussions with other Flare users over which of these two methods is preferable. I think everyone recognizes that each of them has pros and cons.

My preference is to use properly nested lists in the HTML and complex selectors in the CSS. My preference for this goes way back to the beginning of my career when I was writing documentation for a company that did a ton of business with the United States government, and they had a requirement that all of our docs needed to meet accessibility requirements for screen readers. In that scenario, properly tagging content is very important, and we were required to use <ol> and <ul> tags for lists. Why? Because that's what they are. They aren't paragraphs. It's entirely possible that other countries have different requirements.

Besides that point though, I personally just prefer using the complex selectors rather than applying style classes all over the place. I've consulted with a lot of teams the past few years, and I find that teams generally get more consistency using complex selectors rather than paragraph classes, assuming everyone on the team knows how to properly nest lists.

[Nita Beck]

I totally agree with Daniel for the reasons he states.

In my own practice, I always strive for simplicity, and I think complex selectors for lists are much preferable to paragraph styles that mimic lists. Lists styled with complex selectors are just easier to create as one composes. I also think said lists are more "future proof" than paragraphs whose styles mimic lists. No matter what kind of output comes down the pike someday, it is highly likely to know how to render properly structured lists.

I also think that using complex selectors for lists makes it easier for less-savvy authors on a team to not get into trouble.

I've done work with clients whose lists are set up in such "fussy" ways, in many cases with a first list item (as in, having a "first list item" style applied), a next list item (as in, having a "next list item" style applied), last list item, paragraph within a list item, etc. etc. I see that they start an ordered list, then stop the list so they can insert a paragraph of a specific style so that it aligns correctly with the prior list item, then start a new ordered list for which they have to explicitly set the next list item to the next number, then even stop that list and then start a new list that will be indented under the prior list, and so on. Setting up a list this way is just so painful, so time-consuming! It all *looks* OK in output, but its underlying structure is poor. If the Flare authors had just set up a straight up ordered list, used complex selectors (such as ol ul and ol ol) to deal with the second-level list items, and used paragraphs within list items, they would have a very cleanly structured list that will just be so much more easier to maintain in the long run than the "fussy" mimic-lists.

Where the "fussy" mimic-lists have hurt my clients is when they want to adapt their content to a new output/medium, the task they've hired me to do. What might have yielded the right result in one output suddenly is a mess in the new output. It really doesn't take me too much time to convince them to clean up the structure of their lists for the sake of their adaptability and ongoing maintenance.

[Wendy F]

Thanks all for the very good information!

Are there any advantages to using AutoNumbering styles? We are coming from many years of working with FrameMaker & RoboHelp so everyone here is very comfortable using styles. Hopefully, I can convince my team that complex selectors are the way to go.

Wendy