user-defined auto-numbered lists and OL

[fchan]

What are the pros and cons of using the ol style as opposed to defining your own auto-numbered lists? I can think of two advantages of defining a style:
(1) you can format the number (e.g., using bold)
(2) you can cross-reference the number (e.g., In the sentence "Repeat step 2 through step 5", the "2" and "5" are x-references).

In my case the numbers are simple numbers such as 1, 2, and a, b, etc., not 1.2 or 2.3, etc. I think a user-defined style probably is better but I'd like to know whether I've overlooked anything.

[sfoley]

I think a user-defined style probably is better but I'd like to know whether I've overlooked anything.

A few cons:
- Semantics: it's harder for automated tools to parse your content. This might include screen readers, which would reduce accessibility.
- Consistency: It's unlikely you'll be able to exactly mimic the indentation used in multiple, different browsers. So, you'd have to use auto-numbers for every single list in your project, or risk having content that has two slightly-different-looking numbered lists next to each other. And then you'd have to use them in other projects, too, just in case you wanted to ever import that original project ...
- Bloat: Flare usually converts auto-numbers to tables. There's a lot of extra code generated for that, and it makes your content take longer to download (it adds up!), more difficult to debug, and less flexible to lay out in a browser.

Your pros are not particularly compelling for me:
- If you want your list items to be bold, you can always wrap everything in paragraph tags (press Ctrl+; to convert a list item into a paragraph item, define font-weight: bold for your list items, and then set font-weight: normal for your paragraphs). This avoids all of the cons mentioned above.
- As for bookmarking the number, I've found it is more useful to refer users to the entire heading because it gives them context. For example, "Repeat Steps 2–5 in the previous procedure, Making Widgets." Procedures shouldn't ever be so long that it is less confusing to drop someone in the middle.

[LTinker68]

- Bloat: Flare usually converts auto-numbers to tables. There's a lot of extra code generated for that, and it makes your content take longer to download (it adds up!), more difficult to debug, and less flexible to lay out in a browser.

Not always; it depends on how you set up the auto-number format.

As for bookmarking the number, I've found it is more useful to refer users to the entire heading because it gives them context.

Not everyone likes doing it that way. I will at times have something like that. I will also have something like "see Step 2 above", and the beauty of the xref is that if I add a step before step 2, I don't need to change my text -- it will pick up the new numbering itself, and since you can't xref to an HTML list item, then if I did add a step before step 2, then I'd have to remember to look for any instances where I'm reference a step number and adjust them accordingly.


You also cannot do complex numbering using the HTML lists. For instance, you can't do 1.1.1 or 2.8.3 or 3.a.I, etc., with HTML lists, but you can with auto-numbering.

If you're not doing complex numbering, then there's nothing that says you can't have a mix in your project. For example, for a straight list if items, I might use an HTML list. For a list of items where I want to xref to one of them, then I use an auto-number format. I don't generally mix-and-match in a topic, though. Even if you are doing complex numbering you can have a mix in your project, but for consistency in the output I tend not to have a mix when complex numbering is used.

Oh, and with auto-numbers, you can also combine things like the chapter number variable, so you could have Step 2.4 or Step 2-4 for the fourth step in chapter 2.

[sfoley]

Not always; it depends on how you set up the auto-number format.

Thus the 'usually' bit. I've always seen table layouts when I create a format that matches an ordered list, though.

Not everyone likes doing it that way. I will at times have something like that. I will also have something like "see Step 2 above", and the beauty of the xref is that if I add a step before step 2, I don't need to change my text -- it will pick up the new numbering itself, and since you can't xref to an HTML list item, then if I did add a step before step 2, then I'd have to remember to look for any instances where I'm reference a step number and adjust them accordingly.

The way I handle it is to avoid mentioning steps for a given procedure unless I'm writing within the same topic. That way, I can always link safely to the procedure (or topic) title, and the introduction offers more precise directions for their particular task. I realize that's a style preference, but I've always hated documentation that randomly drops me in the middle of a procedure—with the instructions left behind at the previous hyperlink.

You also cannot do complex numbering using the HTML lists. For instance, you can't do 1.1.1 or 2.8.3 or 3.a.I, etc., with HTML lists, but you can with auto-numbering.

You can if you use CSS2. This example will automatically add .x to each level of an ordered list (1 > 1.1 > 1.1.1, etc.):

Code: Select all

ol { counter-reset: item; }
li { display: block; }
li:before { content: counters(item, ".") " "; counter-increment: item; }

I prefer avoiding complex numbering altogether, but I recognize it's not always possible for some clients. This example works in IE8+, so it will work for anyone who's already chosen to use the HTML5 skin.

[crdmerge2]

Be advised that the :before and :after selectors are not recognized in IE8 if Compatibility Mode is enabled.


Good luck,
Leon

[kwag_myers]

I use an ol.substeps and li.substep with a list style type of lower-alpha for walking a novice user through something like using Command Line. This allows me to write to two levels of users, as savvy users can visually skip over the familiar while not neglecting those who may need the additional information.

I gave up on the :before and :after thing because I could never get the results I was looking for. For webhelp, I use mc-auto-number-format, but that doesn't work for print output.

[LTinker68]

Be advised that the :before and :after selectors are not recognized in IE8 if Compatibility Mode is enabled.

That's interesting. Why would compatibility mode affect that?

Anyone know of a resource that lists what compatibility mode in IE will and will not affect? I don't generally think about compatibility mode because I don't set my browser to that, but I guess it's something I should get in the habit of checking. Luckily most of my users are internal so I don't have to worry about it as much, but it would probably be a good reference to keep handy, if such a reference list exists.

[crdmerge2]

Lisa, here's the link you need for what IE8 will/will not support. http://www.quirksmode.org/css/contents.html

The caveat is this: IE8 in Compatibility Mode is, for all intents and purposes, IE7. So review the selector table accordingly.


Good luck,
Leon

EDIT: Duhhhh...forgot the link, initially! Hate when that happens.

[LTinker68]

Thanks!

[sfoley]

Anyone know of a resource that lists what compatibility mode in IE will and will not affect? I don't generally think about compatibility mode because I don't set my browser to that, but I guess it's something I should get in the habit of checking. Luckily most of my users are internal so I don't have to worry about it as much, but it would probably be a good reference to keep handy, if such a reference list exists.

As Leon mentioned, Compatibility Mode basically tells IE to render content as if it were an older version. To my knowledge, the only reasons Flare content would appear in Compatibility Mode are:
- The user (or more likely, their network administrator) forces all web content into this mode
- The writer disabled "Add DOCTYPE declaration to generated topics" for their WebHelp target

You can force IE into compatibility mode for a specific browser version using the X-UA <meta> element, which makes testing a bit easier (just add the meta element to your master page.)

There's not really a canonical, wholly correct reference for supported features by browser versions, but I also recommend quirksmode.org. Mozilla and MSDN also have good references for their respective browsers, but frequently their documentation describes how things -should- work, rather than how they -do- work. Ultimately, the best you can do is test in multiple browser versions every so often, and try to make sure your content remains accessible (if not always perfectly formatted) in those older versions.

[cbdebris]

I have found it pretty easy to use autonumbering across browsers, at least in DotNetHelp and WebHelp. I include a 1-em margin in the <body> and go from there.