Revert "Verification steps" back to "Verification"

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

Revert "Verification steps" back to "Verification" #147

Closed jherrman closed 3 years ago

jherrman commented 3 years ago

This is not a major issue, but as I mention in https://github.com/redhat-documentation/modular-docs/issues/68#issuecomment-696133951 , the template change from "Verification" to "Verification steps" seems to me unwarranted and counter-productive:

The term "Verification" by itself communicates the meaning sufficiently.
When there is only a single verification step (which is pretty often), using the longer title is stylistically pretty awkward even if you put it into singular.
By the same logic, we'd have to say for example "Procedure steps", or "Prerequisite items", or "Locations of additional resources".

Therefore, I would suggest we revert the procedure template to just say "Verification" again.

mjahoda commented 3 years ago

Furthermore, you don't need to remind yourself to remove s from steps when there is only one step.

IngridT1 commented 3 years ago

I agree with Jirka. I didn't think that "Verification" was always in the form of steps.

sterobin commented 3 years ago

@jherrman We discussed in our mod docs call with @emmurphy1 , @rkratky , and @fbolton , and we don't know that Verification even needs to be part of the template at all. It's not going to be used very often, certainly not to the extent of the other labels prescribed in the template. Do you or does anyone feel strongly that this even merits mention in the official mod doc template? It seems that we're getting too finite and prescriptive with mentioning that at all. If we feel strongly to keep it, then I'll revert to Verification, which is indeed better, but otherwise, probably cleaner/better simply to not get into it and leave it to writers as needed.

@IngridT1 , @mjahoda , FYI ^^

sterobin commented 3 years ago

@jherrman , for the sake of time, I've just addressed the issue at hand. I think whether or not it should be there is a separate issue so am leaving it, with your suggested revision. Please review the PR below and approve.

Incorporated in PR #148, pending approval.

rolfedh commented 3 years ago

I believe taking incremental steps such as this one to simplify the templates is beneficial. Because it is infrequently used, we should remove "Verification steps" and similar items from modular-docs/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc.

We should also update the "Procedure verification steps" subsection of modular-docs-manual/content/topics/module_guidelines-procedure.adoc" to indicate that the prefered heading should be "Verification."

Also, outside of this issue, it might also be helpful to provide:

Guidance on when to move verification steps from a procedural topic to assemblies associated with the "Configure and Verify" portion of the product lifecycle.
A job aid or checklist to help authors of procedure modules check required elements and consider optional elements, such as having a "Verification" subsection.

sterobin commented 3 years ago

@rolfedh I agree with you, my preference is still to remove it altogether from the template and from the doc. I was just attempting here to take the path of least resistance, since it's quite a trivial thing anyway. I've updated the heading in the manual portion to remove "steps", but I'm not willing to make many more improvements or add more details to it since I really don't have much of a testimony for it's existence anyway.

rolfedh commented 3 years ago

@sterobin Yes. At a minimum, I'd say remove "steps" and consider this issue closed. I'm just offering some related follow-on suggestions, which I should probably move to a new topic provided by GitHub's new discussion feature. If they gain traction, I'll create new issues for them. Please don't let them hold you up from completing this task.

sterobin commented 3 years ago

@rolfedh Gotcha. Sounds good. Would you mind reviewing and approving PR #148 then? Will see what others say.

jherrman commented 3 years ago

@sterobin I would say that most of our procedure modules should include instructions to verify that the intended goal of the procedure has been achieved - apart maybe from procedures where the result of the procedure is immediately and plainly obvious.

Whether to keep this a distinct "sub-procedure" of the module or keep it in the Procedure steps is a good question - especially given that individual Procedure steps are not-uncommonly verifications for the previous step/s). In my opinion, nevertheless, keeping it separate visually reinforces what result the reader should look for, and also reminds the writer that they should include a verification method in the first place. So, I would keep it in.

In addition, the current template quite explicitly states that this section is not mandatory ("Delete this section if it does not apply to your module"), so I'd say that is the best of both worlds.

jenmalloy commented 3 years ago

@jherrman, @sterobin I think that the need for verification steps depends greatly on the software a writer is documenting. For example, software that mostly uses a user interface typically has little need for verification steps, since the user typically receives a visual confirmation of some kind (or can easily see that a procedure was successful), whereas software that relies heavily on the command line might require verification steps to confirm that a command ran as expected. (I recognize that this doesn't answer the question of should it remain in the template though.)

sterobin commented 3 years ago

@jenmalloy @jherrman, Understood. I've retained for now either way, with the mentioned tweaks. Thanks.