| <?xml version="1.0" encoding="UTF-8"?> |
| <org.eclipse.epf.uma:ContentDescription xmi:version="2.0" |
| xmlns:xmi="http://www.omg.org/XMI" xmlns:org.eclipse.epf.uma="http://www.eclipse.org/epf/uma/1.0.5/uma.ecore" |
| xmlns:epf="http://www.eclipse.org/epf" epf:version="1.5.0" xmlns:rmc="http://www.ibm.com/rmc" |
| rmc:version="7.5.0" xmi:id="-8m7FBotgWiBdSnmd383viQ" |
| name="general_method_element_authoring_guidelines,_jLqqIOFIEdumFeaOJSgmnQ" guid="-8m7FBotgWiBdSnmd383viQ" |
| changeDate="2008-10-30T09:15:51.968-0700" version="1.0.0"> |
| <mainDescription><p>
 |
| <span style="mso-spacerun: yes">When detailing method elements, be sure to:</span>
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Use the individual fields of the method element (and associated guidance) instead of putting all the details in the
 |
| Main description field. This&nbsp;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.
 |
| </li>
 |
| <li>
 |
| Keep text sparse to allow the reader to quickly scan and locate the information they want.
 |
| </li>
 |
| <li>
 |
| Document process-dependent information separate from the method content element definition.&nbsp;Method
 |
| content&nbsp;elements should&nbsp;be process independent. Any minor differences/tweaks to the elements based on
 |
| where they occur in&nbsp;a particular process or lifecycle&nbsp;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.
 |
| </li>
 |
| <li>
 |
| Define associations to guidance, not just hyperlinks in the text.&nbsp;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.&nbsp;This ensures that Method Composer will help flag those cases where the referenced guidance is not included
 |
| in the configuration.
 |
| </li>
 |
| <li>
 |
| Adhere to the recommended guidelines for textual content.&nbsp;See <a class="elementLink"
 |
| href="./../../../core.mdev.common.base/guidances/reusableassets/formatting_and_writing_tips_for_method_authors_F218DBA8.html"
 |
| guid="_sEOcoJcDEd2sTqxclDgvog">Formatting and Writing Tips for Method Authors</a>.
 |
| </li>
 |
| <li>
 |
| 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.&nbsp;
 |
| </li>
 |
| <li>
 |
| Maintain version histories.&nbsp;For more information, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/maintaining_change_histories_and_version_numbers_B83271.html"
 |
| guid="_k91OkFpBEdutiI3y4Hpy9Q">Guideline: Maintaining Change Histories and Version Numbers</a>.&nbsp;
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| For guidelines on detailing the fields that are common across all method elements, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/detailing_common_method_element_fields_940D3CE0.html"
 |
| guid="_zVLrkJZwEd2ireJkqESkdQ">Guideline: Detailing Common Method Element Fields</a>.
 |
| </p>
 |
| <p>
 |
| Method elements can be detailed using templates.&nbsp;For more information, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/detailing_method_content_using_templates_C2B4A444.html"
 |
| guid="_mHp3UOurEdydutqrlpQKOw">Guideline: Detailing Method Content Using Templates</a>.
 |
| </p></mainDescription> |
| </org.eclipse.epf.uma:ContentDescription> |
