Skip to content

Address issues #138 (numbered lists) and #147 (verification) #148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 14, 2021
Merged

Address issues #138 (numbered lists) and #147 (verification) #148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4ea380e
Address issues #138 and #147
sterobin Jan 13, 2021
6d29b76
Tweak proc verification steps title
sterobin Jan 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions modular-docs-manual/content/topics/module_guidelines-procedure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor Author

@sterobin sterobin Jan 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sterobin Yes, that looks good to me.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @bobjohnsrh


[discrete]
== Procedure verification steps
== Procedure Verification
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sentence case should be used. See #133

Suggested change
== 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

List items with complete sentences should end with periods. See The IBM Style Guide pg. 62.

Suggested change
* 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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 action (or actions) for the user, such as running a command, to determine the success or failure of the procedure
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* 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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto, not complete sentences, so no period.


[discrete]
== Procedure Additional Resources
Expand Down
2 changes: 1 addition & 1 deletion modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor Author

@sterobin sterobin Jan 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For issue #147 @jherman, good with you?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you want @jherrman instead.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perfect, thanks!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

////
Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure.
////
Expand Down