GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — Address issues #138 (numbered lists) and #147 (verification) by sterobin · Pull Request #148 · redhat-documentation/modular-docs

Conversation

sterobin commented Jan 13, 2021 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Contributor

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?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions


          Address issues redhat-documentation#138 and redhat-documentation#147

4ea380e

sterobin requested review from bobjohnsrh, emmurphy1, fbolton, rkratky and rolfedh

January 13, 2021 14:14

sterobin added the under review label

Jan 13, 2021

This was referenced Jan 13, 2021

Clarification required regarding numbered lists #138

Closed

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

Closed

sterobin requested a review from IngridT1

January 13, 2021 14:17

sterobin commented

Jan 13, 2021

View reviewed changes

Comment thread

modular-docs-manual/content/topics/module_guidelines-procedure.adoc Outdated


		[discrete]
		== Procedure verification steps
		== Procedure Verification Steps

sterobin Jan 13, 2021 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

sterobin commented

Jan 13, 2021

View reviewed changes

Comment thread

modular-docs-manual/content/topics/module_guidelines-procedure.adoc


		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.

sterobin Jan 13, 2021 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Contributor Author

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

bobjohnsrh Jan 13, 2021

Copy link

Copy Markdown

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

sterobin Jan 13, 2021

Copy link

Copy Markdown

Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Thanks @bobjohnsrh

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

sterobin commented

Jan 13, 2021

View reviewed changes

Comment thread

modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc

		. Use an unnumbered bullet (*) if the procedure includes only one step.

		.Verification steps
		.Verification

sterobin Jan 13, 2021 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Contributor Author

There was a problem hiding this comment.

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?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

VladimirSlavik Jan 13, 2021

Copy link

Copy Markdown

Contributor

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

jherrman Jan 13, 2021

Copy link

Copy Markdown

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Perfect, thanks!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

sterobin Jan 13, 2021

Copy link

Copy Markdown

Contributor Author

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions


          Tweak proc verification steps title

6d29b76

sterobin commented

Jan 13, 2021

View reviewed changes

Comment thread

modular-docs-manual/content/topics/module_guidelines-procedure.adoc


		[discrete]
		== Procedure verification steps
		== Procedure Verification

sterobin Jan 13, 2021

Copy link

Copy Markdown

Contributor Author

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

rkratky Jan 14, 2021

Copy link

Copy Markdown

Collaborator

There was a problem hiding this comment.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

rolfedh approved these changes

Jan 13, 2021

View reviewed changes

rolfedh left a comment

Copy link

Copy Markdown

Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

LGTM

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

fbolton approved these changes

Jan 13, 2021

View reviewed changes

fbolton left a comment

Copy link

Copy Markdown

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

LGTM

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

sterobin removed the request for review from IngridT1

January 13, 2021 16:02

emmurphy1 approved these changes

Jan 13, 2021

View reviewed changes

rkratky approved these changes

Jan 14, 2021

View reviewed changes

rkratky left a comment

Copy link

Copy Markdown

Collaborator

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Thanks, @sterobin. Just a couple of nitpicks. Pre-approving.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

modular-docs-manual/content/topics/module_guidelines-procedure.adoc


		[discrete]
		== Procedure verification steps
		== Procedure Verification

rkratky Jan 14, 2021

Copy link

Copy Markdown

Collaborator

There was a problem hiding this comment.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

modular-docs-manual/content/topics/module_guidelines-procedure.adoc


		- 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

rkratky Jan 14, 2021

Copy link

Copy Markdown

Collaborator

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

sterobin Jan 14, 2021

Copy link

Copy Markdown

Contributor Author

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

modular-docs-manual/content/topics/module_guidelines-procedure.adoc

		- 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

rkratky Jan 14, 2021

Copy link

Copy Markdown

Collaborator

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

sterobin Jan 14, 2021

Copy link

Copy Markdown

Contributor Author

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

sterobin merged commit 8ca8b73 into redhat-documentation:master

Jan 14, 2021

Reviewers

rolfedh

rolfedh approved these changes

rkratky

rkratky approved these changes

emmurphy1

emmurphy1 approved these changes

bobjohnsrh

Awaiting requested review from bobjohnsrh

+3 more reviewers

jherrman

jherrman left review comments

VladimirSlavik

VladimirSlavik left review comments

fbolton

fbolton approved these changes

Reviewers whose approvals may not affect merge requirements

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

under review

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

8 participants

Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

Conversation

sterobin commented Jan 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sterobin Jan 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sterobin Jan 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sterobin Jan 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rolfedh left a comment

Choose a reason for hiding this comment

Uh oh!

fbolton left a comment

Choose a reason for hiding this comment

Uh oh!

rkratky left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

sterobin commented Jan 13, 2021 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

sterobin Jan 13, 2021 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

sterobin Jan 13, 2021 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

sterobin Jan 13, 2021 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.