search

redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.
Creative Commons Attribution Share Alike 4.0 International
80 stars 67 forks source link

Clarification required regarding numbered lists #138

Closed bobjohnsrh closed 3 years ago

bobjohnsrh commented 3 years ago

We need to clarify that not all numbered lists are procedures. For example, a process flow is most likely numbered, but it is not a procedure. The list of items in the flow may include actions performed by the system, which are not user actions.

Some writers have reported being directed to recast numbered process flows as procedures. In some cases, the writer responded by implementing a diagram, which creates an accessibility problem as the content of the diagram is not accessible to low vision users.

Clarifying the guidance about numbered lists would help alleviate this problem.

IngridT1 commented 3 years ago

This makes a lot of sense, @bobjohnsrh. I'm glad that you brought this up.

VladimirSlavik commented 3 years ago

+1. When I was a writer this happened more often than I'd like to believe.

sterobin commented 3 years ago

@bobjohnsrh We discussed in our mod doc call and the fact that this issue comes up is surprising and not necessarily a mod doc issue but a stylistic one. I thought it was a generally understood tech comm convention that numbers were used for anything sequential, whether procedures or processes. So the fact that people are overly prescribing what the template means is surprising. At any rate, I'll throw in a quick note in the proc template, sure, but in general in other cases, we're trying to direct stylistic concerns to the Red Hat Supplementary Style Guide instead.

Anyway, will ping you on my PR shortly.

sterobin commented 3 years ago

Incorporated in PR #148, pending approval.