Explanation for single-step lists

[chloeguling]

Most technical writing best practices and style guides dictate that single-step ordered and unordered lists should actually not be lists, but rather regular sentences. This is because if a list is only one item long, it isn't really a list, so a bullet or number is superfluous.

IBM:

Use at least two list items in an ordered list. You can have one item in an unordered list to match the format of other unordered lists in the same area.

However, the Red Hat Supplementary Style Guide contradicts this, so it is therefore what we should follow:

When a procedure contains only one step, use an unnumbered bullet.

In an ideal world, I think we should remove this guidance since the industry across the board tends to say don't use a bullet. However, I know this might not be possible. So, I'd be curious to know why we have this rule? Maybe adding it to the Supplementary SG would add helpful context?

Thank you!

[roldanbob]

I think that the only advantage of maintaining the current RHSSG guidance is that it helps to set off the single step from the surrounding text. But, because the step should be proceeded by a Procedure title, maybe that's not really a consideration.

[IngridT1]

We had this debate when we first created the Modular Documentation guidelines and decided that the bullet for a single-step procedure was a good way to make the step visible. We know that this does not follow the rules for an unordered list, according to IBM, but IBM Style does not have guidelines for a single-step procedure that I can find.

If you look at the Google developer documentation style guide, it recommends using a bullet for a single-step procedure. Other industry style guides have other guidance, but a bullet for a single-step procedure is very common.

I don't see a good reason to revisit this guidance at this point.

[chloeguling]

Thanks @IngridT1! I wasn't necessarily asking to change it, I thought it would be helpful to add exactly what you explained (that it's easier to see) to the supplementary guide. Since it differs from IBM it's helpful for me to see explanations so that i'm not like "hm that's weird, is this just a random variance?"

I know it probably is not top priority to do that.