Merge pull request #531 from bergerhoffer/clarifying-admonitions

Clarifying that both modules AND assemblies shouldn't start with an a…

Author: bergerhoffer

supplementary_style_guide/style_guidelines/structure.adoc

@@ -82,7 +82,7 @@ To help readers find the information that they need or to confirm that they are
 
 [IMPORTANT]
 ====
-Do not start a module with an admonition, even when adding the Technology Preview admonition. Always include a short description before including an admonition.
+Do not start a module or assembly with an admonition, even when adding the Technology Preview admonition. Always include a short description before including an admonition.
 ====
 
 This description is usually at least 2-3 sentences long, and you can scan it in a few seconds. It exists between the title and the main content, connecting them and providing context and disambiguation.
@@ -93,20 +93,20 @@ Follow these guidelines when writing short descriptions:
 ** *What* users must do. This content is similar to what is in the title but should not just repeat the same information.
 ** *Why* users must complete an action. You must build from the information in the title. This content helps users understand why completing an action is important or beneficial to them.
 * Make modules findable and reusable. Ensure that the product name is either in the title or the short description of a module or assembly.
-* If you are documenting two or more ways of completing the same procedure, explain why users would want to choose one or the other. If possible, link to the other ways. 
+* If you are documenting two or more ways of completing the same procedure, explain why users would want to choose one or the other. If possible, link to the other ways.
 * For complex procedures, include some of the key tasks that a customer must complete.
 * Write in plain English and use simple sentences. You can test the reading level of your sentences by using a readability scoring tool.
 * Use active voice and present tense.
 * Avoid self-referential language, such as "This topic covers..." or "Use this procedure to...".
-* Avoid feature-focused language. Focus on what users can accomplish with a product, not on what a product does. For example, avoid phrases such as "This product allows you to...". 
+* Avoid feature-focused language. Focus on what users can accomplish with a product, not on what a product does. For example, avoid phrases such as "This product allows you to...".
 * Use customer-centric language, such as "You can... by..." or "To..., configure...".
 
 .Example short description 1
 --
 ====
 ==== Creating a group and adding a system
 
-Group many systems together in the Edge Management application [*what*] to manage them more easily [*why*]. For example, you can more easily mitigate vulnerabilities and update systems that are alike. 
+Group many systems together in the Edge Management application [*what*] to manage them more easily [*why*]. For example, you can more easily mitigate vulnerabilities and update systems that are alike.
 ====
 --