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

Procedure template: Refine guidance for the first step #183

Closed jenmalloy closed 2 years ago

jenmalloy commented 2 years ago

In the procedure template (https://github.com/redhat-documentation/modular-docs/blob/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc), step one says, "Start each step with an active verb." While in general this is true, often for the first step (and sometimes in subsequent steps, depending on the situation) the user needs to be oriented to where they need to go first. Here's a procedure example from the mod docs reference guide (https://redhat-documentation.github.io/modular-docs/#reusing-modules) to illustrate what I mean: "In the module file that will be reused, add the {context} suffix with a hyphen to the anchor name in the format [id="anchor-name_writing-mod-docs"]."

Conversely, here's an example (from the supplementary style guide) that puts the "orienting" information at the end of the sentence: "Click Metering on the Installed Operators page." As a user, the information I need first is presented last in that sentence. Reversing the order mirrors the order of the actions: "On the Installed Operators page, click Metering." I recognize it's probably too difficult to go into that much detail in the template, but perhaps we can modify the sentence, Start each step with an active verb, to somehow encompass the "reduce cognitive load for the user" principle? (I'm willing to help if you'd like :-) Thanks for listening!

mjahoda commented 2 years ago

Honestly, I have never been tempted to strictly follow the brief hints in the template, but you are right, this might be misleading for someone. I believe that it is just about finding accurate wording that will remain reasonably brief and clear.

emmurphy1 commented 2 years ago

I created https://github.com/redhat-documentation/modular-docs/pull/188 to update the procedure template. After I started with the correction suggested in this issue, I just kept going :-) I've updated the instructions in the template and the reference guide. Please provide feedback @jenmalloy and @mjahoda.

mjahoda commented 2 years ago

@emmurphy1 I have checked your update, and I have provided some suggestions. You have improved the procedure template greatly.

emmurphy1 commented 2 years ago

https://github.com/redhat-documentation/modular-docs/pull/190 merged. @adahms I don't think we need to record this in the decision register. This was an improvement to the instructions in the reference guide and templates.