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
82 stars 68 forks source link

Update procedure module guidelines for single prereqs #86

Closed bhardesty closed 5 years ago

bhardesty commented 5 years ago

This is for Issue https://github.com/redhat-documentation/modular-docs/issues/80.

The consensus is that you should use a bulleted list for all prereqs, even if there's only one. This PR adds a short sentence to state this guidance explicitly.

sterobin commented 5 years ago

@bhardesty, @ritz303, @IngridT1, understood. Did we also decide to use plural "Prerequisties" even when just one? That and the bullets issue were the two parts to this question, so just confirming.

IngridT1 commented 5 years ago

@sterobin Yes, always use the plural, "Prerequisites", even when you have just one.

bhardesty commented 5 years ago

@sterobin @IngridT1 Another option would be to use a phrase that works for both singular and plural prereqs (like, "Before you begin"). But considering that many of us have already implemented the "Prerequisites" term, I think it would be pretty disruptive to change it.

sterobin commented 5 years ago

Good point, @bhardesty. To me, though, "Before you begin" and "Prerequisites" aren't quite the same thing, at least in my cases. IMO, "Before you begin" conveys active steps the user should do pertaining to the upcoming procedure but that really aren't part of that procedure (cases are rare, but I've encountered them), while "Prerequisites" are check-off things that should be done prior to the procedure. I don't have a great example on hand (I'd need to dig a bit) and what I'm saying might not make any sense, but I guess it's just to say that that's another reason to avoid replacing "Prerequisites".

ritz303 commented 5 years ago

@bhardesty : Looks good, and thanks for taking care of this! ACK. I plan on merging this into master next Monday (11/12).