| <?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="-BM4ojokYczyHhUGq2ABN_w" |
| name="new_guideline,_cJbBkCAhEdy1y5bWsXfCCg" guid="-BM4ojokYczyHhUGq2ABN_w" changeDate="2008-10-16T12:20:55.719-0700" |
| version="1.0.0"> |
| <mainDescription><p>
 |
| In general, all noncontributing method elements&nbsp;need a brief description. A brief description provides a one or
 |
| two sentence description of what the element is (in other words, what content the element contains).
 |
| </p>
 |
| <p>
 |
| Brief descriptions should be written at the time the element is identified.&nbsp;A well-written description is
 |
| important because if you find it hard to describe what an element is, it may not be a good element
 |
| </p>
 |
| <p>
 |
| Follow these guidelines when developing method element brief descriptions:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Do not include presentation names in brief descriptions because that makes it harder to change the presentation
 |
| name. Instead, refer to "this &lt;element type&gt;", where &lt;element type&gt; is the type of method element. For
 |
| example, “this role”... or “this guidance".
 |
| </li>
 |
| <li>
 |
| Do not state the obvious. The brief description should not just repeat what can be understood from the element type
 |
| and the presentation name. For example, for Concept: Pattern, don't just say, "This concept describes what a
 |
| Pattern is".&nbsp;Such information does not provide any value.&nbsp;Instead,&nbsp;provide a one or two sentence
 |
| summary of what the element contains.&nbsp;For example, "This concept describes&nbsp;s generalized solution that
 |
| can be implemented and applied in a problem situation (a context) and thereby eliminate one or more of the inherent
 |
| problems."
 |
| </li>
 |
| <li>
 |
| Avoid repeating the brief description in other fields of the method element. If there is nothing more to add to
 |
| what is in the brief description, then omit the other description fields.
 |
| </li>
 |
| <li>
 |
| Make sure that there is a period at the end of the brief description.
 |
| </li>
 |
| <li>
 |
| Check for general spelling and spacing errors.
 |
| </li>
 |
| </ul></mainDescription> |
| </org.eclipse.epf.uma:ContentDescription> |
