Guideline: Detailing Method Elements (General)
This guideline includes method detailing guidelines that are common for all method elements.
Relationships
Main Description

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.

More Information