GV

GeezerVison

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

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Issue119 Concept-module rules are too strict by emmurphy1 · Pull Request #150 · redhat-documentation/modular-docs

Conversation

@emmurphy1

@emmurphy1 emmurphy1 commented Jan 29, 2021

Copy link
Copy Markdown
Collaborator

See Issue 119 for the discussion.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@emmurphy1
issue119 relaxed guidance on instructions in concept modules
8561c99
rolfedh
rolfedh approved these changes Feb 10, 2021
View reviewed changes
@yzimmerm

yzimmerm commented Feb 10, 2021

Copy link
Copy Markdown

= Latency improvement by minimizing memory swapping

[role="_abstract"]
Swapping pages to disk can introduce latency in any environment. To ensure low latency, ensure that you have enough memory in your systems, so that swapping is not necessary. Always size the physical RAM as appropriate for your application and system.

Use the [command]vmstat command to monitor memory usage and watch the [parameter]si (swap in) and [parameter]so (swap out) fields. It is optimal that they remain zero as much as possible.

[literal,subs="+quotes,verbatim"]

$ vmstat
procs -----------memory---------- ---swap--- -----io---- --system-- ------cpu-----
r b swpd free buff cache si so bi bo in cs us sy id wa st
9 0 4186588 517872 28 4366932 0 1 4 207 0 1 9 3 88 0 0
VladimirSlavik reacted with eyes emoji
All reactions
  • 👀 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
sterobin
sterobin reviewed Feb 10, 2021
View reviewed changes
Comment thread modular-docs-manual/content/topics/module_guidelines-concept.adoc
Do not include any instructions to perform an action, such as executing a command.
Avoid including instructions to perform an action, such as executing a command.
Action items belong in procedure modules.
See also link:http://www.informationmapping.com/fspro2013-tutorial/infotypes/infotype2.html[The Six Information Types] at _informationmapping.com_ for ways to present different types of conceptual information: principle, concept, structure, process, fact.

@sterobin sterobin Feb 10, 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.

Wording addition per meeting. Just a start. Feel free to tweak as needed.

... procedure modules. However, in some cases a concept or reference can include suggested actions when those actions are simple, are highly dependent on the context of the module, and have no place in any procedure module. In such cases, ensure that the heading of the concept or reference remains a noun phrase and not a gerund.

For example, see the following section for link:https://access.redhat.com/documentation/en-us/red_hat_process_automation_manager/7.9/html-single/developing_decision_services_in_red_hat_process_automation_manager/index#bound_variables_in_patterns_and_constraints[Bound variables in patterns and constraints] and other sections that follow it in the example document. These concept and reference modules contain actions that are not suitable for standalone procedure modules but are relevant actions to understand in the context of the concept or reference being described.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
sterobin
sterobin reviewed Feb 10, 2021
View reviewed changes
Comment thread modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc Outdated
* Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
* Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
* Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.
* Avoid including instructions to perform an action, such as executing a command. Action items belong in procedure modules.

@sterobin sterobin Feb 10, 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.

Not sure how much of the above actual doc instruction to duplicate here in the template. Maybe the same instruction from above but exclude the example? Trying to be consistent and clear while not burdening the template too much.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@emmurphy1
issue119 updated with feedback
ebcb3ee
ncbaratta
ncbaratta approved these changes Mar 29, 2021
View reviewed changes

@ncbaratta ncbaratta 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
fbolton approved these changes Mar 30, 2021
View reviewed changes
rolfedh
rolfedh approved these changes Mar 31, 2021
View reviewed changes
rkratky
rkratky reviewed Mar 31, 2021
View reviewed changes
Comment thread modular-docs-manual/content/topics/module_guidelines-concept.adoc
Do not include any instructions to perform an action, such as executing a command.
Action items belong in procedure modules.
Avoid including action items. Action items belong in procedure modules. However, in some cases a concept or reference module can include suggested actions when those actions are simple, are highly dependent on the context of the module, and have no place in any procedure module. In such cases, ensure that the heading of the concept or reference remains a noun phrase and not a gerund. For example, see link:https://access.redhat.com/documentation/en-us/red_hat_process_automation_manager/7.9/html-single/developing_decision_services_in_red_hat_process_automation_manager/index#bound_variables_in_patterns_and_constraints[
"Bound variables in patterns and constraints"] and the sections that follow it. These concept and reference modules contain actions that are not suitable for standalone procedure modules but are relevant actions to understand in the context of the concept or reference being described.

@rkratky rkratky Mar 31, 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
"Bound variables in patterns and constraints"] and the sections that follow it. These concept and reference modules contain actions that are not suitable for standalone procedure modules but are relevant actions to understand in the context of the concept or reference being described.

Sorry, something went wrong.

Uh oh!

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

@emmurphy1 emmurphy1 Jun 25, 2021

Copy link
Copy Markdown
Collaborator 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 can you explain why you don't want to include the examples?This is for the guide and not the template. I think the examples are very useful. The concept is somewhat abstract and I am afraid that writers will misinterpret this exception and use if for more explicit action.

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-concept.adoc Resolved

Uh oh!

There was an error while loading. Please reload this page.
yzimmerm
yzimmerm approved these changes Apr 7, 2021
View reviewed changes
emmurphy1 and others added 3 commits May 3, 2021 14:11
@emmurphy1 Robert Krátký
Update modular-docs-manual/content/topics/module_guidelines-concept.adoc
e3742d0 
Co-authored-by: Robert Krátký <[email protected]>
@emmurphy1 Robert Krátký
Update modular-docs-manual/content/topics/module_guidelines-concept.adoc
e1aecec 
Co-authored-by: Robert Krátký <[email protected]>
@emmurphy1
issue119 fixed typo
68a18f4
yzimmerm
yzimmerm approved these changes Jul 1, 2021
View reviewed changes
@emmurphy1
issue119 fixed conflict
ea5721a
Preeticp
Preeticp approved these changes Jul 14, 2021
View reviewed changes
@emmurphy1 emmurphy1 changed the title WIP: Issue119 Concept-module rules are too strict Issue119 Concept-module rules are too strict Aug 4, 2021
@emmurphy1
emmurphy1 merged commit 0a859e3 into master Aug 4, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rkratky rkratky rkratky left review comments
@rolfedh rolfedh rolfedh approved these changes
+5 more reviewers
@sterobin sterobin sterobin left review comments
@ncbaratta ncbaratta ncbaratta approved these changes
@fbolton fbolton fbolton approved these changes
@Preeticp Preeticp Preeticp approved these changes
@yzimmerm yzimmerm yzimmerm 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

None yet

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

@emmurphy1 @yzimmerm @ncbaratta @rolfedh @fbolton @rkratky @Preeticp @sterobin
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.