Why not put list steps in bold?

[rkratky]

Laura Bailey:

I am curious about "NOTE: Do not put steps in bold." beside ordered lists - I've often titled steps in procedures, and have used bold on the first part of an ordered list item to make the main action clearer to those who are skimming rather than reading in-depth. What's our reasoning here?

[rkratky]

The main reason for including the note is that some writers would put entire lists in bold for some reason. This is to prevent that.

I'm not sure what you mean by "titled steps in procedures"... Do you really give titles to individual items in ordered lists? I can't quite imagine how that looks like, but I would argue that if something is substantial enough to require a heading/title of its own, then perhaps it should not be formatted/marked up as a mere list item.

[laubai]

Good question. I wouldn't do this for a list being used as a list; it's more in the case where a list is being used because there is no markup for a procedure.

Here's an example: https://access.redhat.com/documentation/en-us/red_hat_hyperconverged_infrastructure/1.0/html/deploying_red_hat_hyperconverged_infrastructure/task-config-rhgs-using-cockpit

The steps here aren't exactly complex, but they're also not 4-10 words per step. Bolding the first line does two things:

1. Readers who just want to jog their memory can skim through and focus on the step titles.
2. Readers who need the extra guidance in the step have a clear focus as to the underlying purpose of the action performed in the step.

Putting a whole list in bold is definitely not necessary, but I feel using bold text to emphasise the key action can help.

[asteflova]

I was a bit surprised to see the note in the AsciiDoc conventions too, but for a different reason. It seems to be a 'best practice' for documentation style thing rather than a markup thing. In the same spirit, one could also add notes about other best practices: avoiding procedures with more than two levels, avoiding procedures with more than 7 steps, ...

Pure markup guidelines tend to be very simple and unambiguous: you are documenting a command and need to know what markup to use. Or you are including an image and need to know whether you need to include a title or not.

Style guidelines (like whether to use bold or not and where) are often more ambiguous and include more gray areas, which Laura illustrates in her comment.

I think it would be best to limit the AsciiDoc conventions to markup guidelines, and leave the style guidelines to our style guides (the IBM style guide includes some recommendations on using highlighting, including bold text, although it doesn't address steps in procedures specifically).

[rkratky]

@asteflova, there's a persistent misunderstanding wrt the purpose of these guidelines. Their aim IS NOT to teach writers how to use adoc mark-up. There are other excellent resources for that. The aim IS to standardize the look of our docs. The fact that the look is directly dependent on mark-up used is incidental.

So,

It seems to be a 'best practice' for documentation style thing rather than a markup thing.

Exactly. These guidelines should probably really be named "Element style guidelines with a bonus: what adoc mark-up to use to achieve the desired look".

one could also add notes about other best practices: avoiding procedures with more than two levels, avoiding procedures with more than 7 steps, ...

Let's not confuse style as in look and style as in stylistics. These guidelines are about the former. Your example is about the latter.

you are documenting a command and need to know what markup to use

Yes, so that when the doc is rendered, all commands look the same.

leave the style guidelines to our style guides (the IBM style guide includes some recommendations on using highlighting, including bold text, although it doesn't address steps in procedures specifically)

Again, mixing style and style... Although, I admit, I had no idea the IBM Style Guide talked about looks. I'm pretty sure its recommendations in this area are not universally followed within CCS. Regardless, we now have our own set of recommendations for this area: these guidelines.

.........................

Anyway: The big fail here is the recurring misunderstanding about the purpose of these guidelines. Ideas on how to remedy the situation are welcome. Would a simple retitling help?

[rkratky]

@laubai, I guess I understand now what you mean. Except, the doc you link to doesn't use any bolding in the 'step titles'. Be that as it may, I think this is a special case and should be determined by the writer in question.

The note in the guidelines is intended to discourage wholesale bolding of list items (which I myself have not encountered, but other members of the team witnessed and thought it prudent to include a note about it).

[rkratky]

The big fail here is the recurring misunderstanding about the purpose of these guidelines. Ideas on how to remedy the situation are welcome. Would a simple retitling help?

We should add an intro paragraph. => #14

[bergerhoffer]

@laubai I'm not sure that I see bolded steps in the example doc that you shared. That looks totally fine to me. The only things I see bolded are GUI items, which is our recommendation for GUI items.

Below is an example of an old EAP doc that bolds the entire first sentence of a step. That is what we're saying not to do. Having a concise first sentence of a step on its own line, and the rest of the details in paragraphs, etc. below it should be sufficient. Though I've also seen instances where the first sentence of a step was bolded and it was in a giant paragraph and that is not good either.

https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Installation_Guide/sect-RPM_Installation.html#Install_JBoss_Enterprise_Application_Platform_6_RPM_Installation

[chrisnegus]

I totally agree with @laubai about marking a few words at the beginning of steps in bold, to emphasize key actions. I've had discussions with other writers in Red Hat who like this approach as well.