Address issues #138 (numbered lists) and #147 (verification) #148
Conversation
sterobin
requested review from
rolfedh,
fbolton,
rkratky,
emmurphy1 and
bobjohnsrh
| [discrete] | ||
| == Procedure verification steps | ||
| == Procedure Verification Steps |
There was a problem hiding this comment.
I changed to headline style against prescribed convention of sentence case strictly for consistency because the entire manual is headline style, making all of it non-compliant. Issue #133 will at some point address the headline style issue throughout. Several other mechanical issues need to be addressed throughout also, but that will be done as a separate effort.
| @@ -32,12 +32,14 @@ The procedure consists of one or more steps required to complete the procedure. | |||
|
|
|||
| For single-step procedures, use an unnumbered bullet instead of a numbered list. | |||
|
|
|||
| NOTE: Not all numbered lists in documentation are procedures. You can also use numbered lists in any module type for non-procedural sequences, such as a process flow of system actions. | |||
There was a problem hiding this comment.
For issue #138 . @bobjohnsrh , good with you?
@emmurphy1 I know we discussed putting this note in the proc template, but after I tried that, it didn't make sense to me there (strange to say something in a proc template about permitting numbered elements in other template types) and it also was cluttering the template.
There was a problem hiding this comment.
@sterobin Yes, that looks good to me.
There was a problem hiding this comment.
Thanks @bobjohnsrh
| @@ -41,7 +41,7 @@ Write a short introductory paragraph that provides an overview of the module. Pr | |||
|
|
|||
| . Use an unnumbered bullet (*) if the procedure includes only one step. | |||
|
|
|||
| .Verification steps | |||
| .Verification | |||
There was a problem hiding this comment.
I think you want @jherrman instead.
There was a problem hiding this comment.
Thanks @VladimirSlavik Sorry, it wasn't populating Jiri's git name because I guess he isn't in the review group or something. Thanks for the correction!
@jherrman, thanks.
| [discrete] | ||
| == Procedure verification steps | ||
| == Procedure Verification |
There was a problem hiding this comment.
I've made the title headline style strictly for consistency, even though it is against CCS convention of sentence style in headings. Issue #133 will eventually address the heading style issue throughout.
There was a problem hiding this comment.
Sentence case should be used. See #133
| == Procedure Verification | |
| == Procedure verification |
| [discrete] | ||
| == Procedure verification steps | ||
| == Procedure Verification |
There was a problem hiding this comment.
Sentence case should be used. See #133
| == Procedure Verification | |
| == Procedure verification |
| This section is optional. Provide the user with one or more steps to verify that the procedure provided the intended outcome. This may consist of: | ||
|
|
||
| - An example of expected command output or 'pop-up' window the user should receive when the procedure is successful. | ||
| - An 'action' (or 'actions') for the user, such as running a command, to determine the success or failure of the procedure. | ||
| * An example of expected command output or pop-up window the user should receive when the procedure is successful |
There was a problem hiding this comment.
List items with complete sentences should end with periods. See The IBM Style Guide pg. 62.
| * An example of expected command output or pop-up window the user should receive when the procedure is successful | |
| * An example of expected command output or a pop-up window the user should receive when the procedure is successful. |
There was a problem hiding this comment.
@rkratky For the headline case, I already explained in my comment on it that I intentionally made it headline style against the compliance for the sake of being consistent with all other headings in the manual for now, and I referenced issue #133 . I'd prefer to not have a random sentence-style heading that looks like a mistake until someone can address the issue throughout.
Regarding the periods, no, those aren't complete sentences which is why I removed the periods, per IBM SG. A complete sentence must have a subject and predicate (main verb). These are all just lengthy subjects.
| - An example of expected command output or 'pop-up' window the user should receive when the procedure is successful. | ||
| - An 'action' (or 'actions') for the user, such as running a command, to determine the success or failure of the procedure. | ||
| * An example of expected command output or pop-up window the user should receive when the procedure is successful | ||
| * An action (or actions) for the user, such as running a command, to determine the success or failure of the procedure |
There was a problem hiding this comment.
| * An action (or actions) for the user, such as running a command, to determine the success or failure of the procedure | |
| * An action (or actions) for the user, such as running a command, to determine the success or failure of the procedure. |
There was a problem hiding this comment.
Ditto, not complete sentences, so no period.
Addresses #138 (numbered lists) and #147 (verification) in procedure content.
@bobjohnsrh , @jherman, @IngridT1 , @emmurphy1, @rkratky , @fbolton , @rolfedh Can you review, provide any feedback, and approve?