Skip to content

Issue119 Concept-module rules are too strict #150

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 6 commits into from
Aug 4, 2021
Merged

Issue119 Concept-module rules are too strict #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8561c99
issue119 relaxed guidance on instructions in concept modules
emmurphy1 Jan 29, 2021
ebcb3ee
issue119 updated with feedback
emmurphy1 Feb 19, 2021
e3742d0
Update modular-docs-manual/content/topics/module_guidelines-concept.adoc
emmurphy1 May 3, 2021
e1aecec
Update modular-docs-manual/content/topics/module_guidelines-concept.adoc
emmurphy1 May 3, 2021
68a18f4
issue119 fixed typo
emmurphy1 Jun 25, 2021
ea5721a
issue119 fixed conflict
emmurphy1 Jul 1, 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
5 changes: 3 additions & 2 deletions modular-docs-manual/content/topics/module_guidelines-concept.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ The concept body describes the subject of the concept module.
Apart from paragraphs, you can use other AsciiDoc elements, such as lists, tables, or examples.
Consider including graphics or diagrams to speed up the understanding of the concept.

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. 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.
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
"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.

Copy link
Collaborator Author

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.


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.
Copy link
Contributor

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.


If the concept module is large and complex, consider splitting the concept module into multiple standalone concept modules. If you cannot split the module into meaningful standalone modules, consider using subheadings in the module to structure the content for improved reader navigation. If you use subheadings in a concept module, you can add the `[discrete]` tag to exclude each subheading from the table of contents, if needed. However, in many cases, subheadings are helpful to include in the table of contents to improve content searchability.
Expand Down
3 changes: 2 additions & 1 deletion modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ The contents of a concept module give the user descriptions and explanations nee

* 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 action items. Action items belong in 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.


[role="_additional-resources"]
.Additional resources
Expand Down