When detailing method elements, be sure to:
-
Use the individual fields of the method element (and associated guidance) instead of putting all the details in the
Main description field. This separates and simplifies the detailed text so the reader can easily focus on the
information they’re interested in. Specifically, use the Brief Description or Purpose sections of method content to
state the purpose or conclusion of the idea that’s being communicated. Use the remaining sections to provide a
detailed explanation of the subject. A method element should immediately communicates the specific idea that’s
being described. Reading the rest of the sections is useful to understand the detail of the subject.
-
Keep text sparse to allow the reader to quickly scan and locate the information they want.
-
Document process-dependent information separate from the method content element definition. Method
content elements should be process independent. Any minor differences/tweaks to the elements based on
where they occur in a particular process or lifecycle can be captured in the processes in which the
element appears (more on this below). This maximizes the reuse of the method content across processes.
-
Define associations to guidance, not just hyperlinks in the text. If you link to other guidance from the HTML
of a guidance element, define an association from the guidance element to the guidance you are referring
to. This ensures that Method Composer will help flag those cases where the referenced guidance is not included
in the configuration.
-
Adhere to the recommended guidelines for textual content. See Formatting and Writing Tips for Method Authors.
-
Capture the source of the information being included in the element. This information is important if you ever need
to provide source information for the element for documenting ownership rights.
-
Maintain version histories. For more information, see Guideline: Maintaining Change Histories and Version Numbers.
For guidelines on detailing the fields that are common across all method elements, see Guideline: Detailing Common Method Element Fields.
Method elements can be detailed using templates. For more information, see Guideline: Detailing Method Content Using Templates.
When referring to a specific practice, the name of the practice should be capitalized as it is a specific name. |