This guideline provides guidelines for detailing guidance. For general detailing guidelines that are common to all method elements, see Guideline: Detailing Method Elements (General).

Keep in mind the following guidelines when completing each of the guidance-specific text fields (for guidelines regarding the common fields, see Guideline: Detailing Common Method Element Fields):   

• Main Description: This field is the key field of all guidance elements. 
  Care should be taken to distinguish between guidance that may be embedded and that which should be referenced. When third party material is used, the method author must ensure that permission exists for its use in the intended context.   

For guidance-type-specific guidelines, see the following sections.   

Detailing checklists

The Main description field is optional in a checklist as the key content of a checklist are the check items.

The following fields are specific to checklists:

Check Items:  These fields make up the items in the checklist.  Each check item has:

• Name:  This is the short description of the check item. These should be written as verifiable statements rather than questions, items for consideration, or guidance. If the check item does not always apply the conditions for when to use that check item should be appended to the name in curly brackets { }.   
• Description:  This field is optional. It provides additional detail for the check item. If these are "sub-check items" they should also be written as statements. 

Note: It is usually not necessary to have a main description for a checklist if the required content is covered by the associated check items, conversely it may be feasible to have a checklist with no check items if the text of the main description adequately covers what is to be reviewed   

Detailing examples

When detailing an example:

• Make sure the Brief description summarizes the example, and summarize the context in which it was used. The more specific the better. For example: "This is an example of a requirements management plan for a safety-critical application."
• (optionally) Attach an actual example to the guidance.
• (optionally) In the Main description, you can describe what the example represents and how it guides the user in working with the real work product.

Detailing guidelines

When entering text in the Main description if guideline elements, exceptionally lengthy guidance should either be broken down into multiple guidance elements, or attached as a word document. Note that word documents are difficult to translate, and so should be avoided in commercial content.

Detailing reusable assets

When detailing a reusable asset:

• Make sure the Brief description summarizes the reusable asset, the problem it solves and the context in which it is applicable. The more specific the better.
• Attach an actual reusable asset to the guidance
• In the Main description, describe how to apply the reusable asset

Detailing templates

When detailing a template:

• Make sure the Brief description summarizes the context, format, and tool applicable for this template. For example "This is an informal Word document template." If format such as "letter" versus "A4" is important, that can also be stated.
• Attach actual template files to the guidance
• (optionally) In the Main description, provide information about the structure of template and how to use it. You may want to include a description of how to fill out each section of the template.

Detailing tool mentors

When detailing a tool mentor, explain how to apply a specific tool to accomplish a task, performs a set of steps or instantiates a particular work product. 

Detailing white papers

When detailing a white paper:

Every practice includes the following standard guidance elements:

• How-to-Adopt roadmap: describess how to adopt the practice
• practice guidance element

The following sections provide recommendations on what to include in these elements when detailing the practice.

Detailing the how-to-adopt roadmap

Capture the following in the Main description field:

• Getting Started section: Include information on how to get started using the techniques described in the practice
• Common Pitfalls section: Describe some common pitfalls when adopting the practice

Detailing the practice guidance element

Provide the following content in each of the element fields:

• Brief description:  Include one or two sentences describing what this practice covers.
    
• Purpose: Include content that describes the business value of this practice -- what do you get when you adopt it? This section is essentially the value proposition for the practice. You may want to describe some common problems and how this practice solves those problems.
    
• Goals: This field is not used
    
• Background: This field is not used
    
• Main description: This field is optional.  It can be used to elaborate on the practice. However, it should be kept brief because this is the first page that users are exposed to, and it is better if that page is short so as not to overwhelm them.
    
• How to read this practice: This field is optional.  It can include content on the best way to read this practice:

For example: "The best way to read this practice is to first familiarize yourself with its overall structure -- what it is in it and how it is organized. The best place to start is with the Key Concepts for the practice -- those concepts that are critical to understand in order to adopt the practice. Once you understand the key concepts, you can turn your attention to the Work Products produced by the practice. Then you can review the practices Tasks. From the work products and the tasks, you can access applicable guidance -- guidelines and tool mentors associated with each task provide details of how to perform the task. Templates and checklists associated with the work products guide you in their completion and evaluation. You can also access the guidance provided by the practice directly, via the Guidance folder.

• Levels of adoption: This field is optional. It can be used to provide information about levels of adoption of this practice. For example, you may initially adopt a practice by using a few of the recommended work products and over time use the remaining ones. 
    
• Additional information: Use this field to provide enablement information for this practice. For example: available books, articles, training courses, and so on.
    
• References: These are the associations to all the elements that are considered part of the practice.  For information on defining these associations, see Guideline: Structuring a Practice.