Detailing Method Elements
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].
Method elements can be detailed using templates. For more information, see topic Detailing Method Content Using
Templates in Guideline: Creating Plug-ins, Practices and Configurations.
Detailing Common Method Element Fields
In general, use the individual method element properties to capture specific information about the element. This
simplifies the text so that the reader can easily focus on the information they're interested in.
General information:
Detail information:
Use the Purpose and Description sections of method element 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.
-
Purpose: Describes the reason for the method element.
-
Main description: Provides an extended description that explains what the method element is beyond
what is covered elsewhere.
-
Key considerations: Contains useful material that does not easily fit into any of the other
sections, such as advice and guidance of a critical nature. as well as warnings, cautions, pitfalls and dangers
Version information:
-
Version: The version number of the element. In many cases,
versioning is done at the plug-in level, rather than at the individual element level.
-
Change date: Today's date is entered by clicking in the field. It cannot be removed.
-
Change description: Enter any free-form text. The history of these descriptions is
maintained.
-
Authors: Identify the author(s) of this content.
-
Copyright: The element's copyright. This is generally only completed for the plug-in, since
every element gets the plug-in's copyright, unless it is overridden for a particular element.
Icon:
-
Shape icon: Specify the icon to be displayed in the upper left of the content page when published.
Define a new icon or use one from another plug-in.
-
Node icon: Specify the icon displayed by this node in the tree view of the published site. Define
a new icon or use one from another plug-in.
Detailing Practice Elements
Detailing a Practice is all about fleshing out the details of the individual practice
elements.
All practice detailing work must adhere to the constraints defined for the Practice Framework and for the
practice itself.
When detailing any element that physically resides in a practice, do not refer to elements outside of the
practice.
Exception: practice elements may refer to Work Product Slots and other core elements.
In addition to the method elements included in a practice (for example, tasks, guidance, and so on), every practice
should include the following guidance elements:
-
how-to-adopt roadmap: describes how to adopt the practice
-
practice guidance element
Detailing practice elements in the UMF
When detailing the elements in a practice that exists within the Unified Method Framework (UMF), you must take
into consideration the UMF practice conventions. When detailing the elements in a practice, you may find that you
need to make changes to an element in a Core plug-in. Specifically, you may find that you have content
that would be better shared between practices (for example, a common work product, some shared guidance, or a new
role) and thus you may need to add a new core element or refine an existing core element.
Detailing Work Products
This topic provides guidance for detailing work products (artifacts, outcomes and deliverables).
-
Purpose: The Purpose field describes the reason for the method element. For example, for a
Work Product:
-
Why is the work product produced?
-
How will it be used?
Do not repeat text already stated in other fields, such as the brief description or the main description.
-
Main description. This field is optional for work products. It contains a detailed
description of the work product if the Brief description and Purpose is insufficient. If
the work product has significant state, include a state machine (i.e., a description of the
states and their transitions) in the artifact's Main description.
-
Key Considerations: This field is optional. It contains useful material that does
not easily fit into any of the other sections, such as advice and guidance of a critical nature, as well as
warnings, cautions, pitfalls and dangers.
-
Impact of not having: List and briefly describe the consequences of not producing this
work product. Consider this from the delivery practitioners' point of view. If the work product was not
available, what would be the impact to the execution of the project? What information would the practitioners
not have that they need? Write a short description of the impact.
-
Reason for not needing: List the conditions when the work product might not be needed, and why. Is
the information available somewhere else? Is it of secondary importance to other work products? Is the project
small enough that it is not relevant? Write a short description of the normal reasons why the work product may not
be needed.
-
Guidance: Guidance can be associated to a task to provide further details about the work product.
The type of guidance that is usually associated with a work product includes checklists, examples and templates.
For work-product-type-specific guidelines, see the following sections.
Detailing artifacts
The following fields are artifact-specific:
-
Brief outline: This field is optional. It describes the major sections or information topics
that are covered by the work product. This information should be generic, in other words, not
specific to any particular format or template.
-
Selected representation: This field is optional. It is used when a particular representation
is decided on. For example, a particular company may mandate the use of a particular tool or format.
-
Notation: This field is optional. It describes any notations used by the work product. Either
Brief outline or Notation should be provided, or both [*** I got this last
sentence from the template, but I am not sure what it means. Should it be "not both"? ***] This
field may also contain explanations of any diagrammatic or textual notations. Include notations that are important
or special terms, labels, headers, acronyms, etc. that are used in the artifact. Any items relating to how this is
implemented in a specific template should be included in the description for that template, not here. Note this
section should be general enough to apply regardless of the actual representation option selected, unless there are
multiple notations such as IDEF1X or UML, in which case an overview of each can be included (preferably as
contributions from the related techniques).
-
Representation options: This field is optional. Describe alternative representations for this
work product.
Detailing deliverables
The following fields are deliverable-specific:
-
External Description: This field is intended to be a description of the deliverable that the
client will read. It is usually copied into a Statement of Work or other agreement, or into sales and marketing
material. The content of this field may require legal approval of some sort. Seek guidance from the method
authoring consultant. Keep to a description (what the deliverable is) rather than its use in an engagement. Build
on the purpose but differentiate between the what and the why of the deliverable. The description is about what the
deliverable is. The description must be understood by potential clients.
-
Packaging Guidance: This field is intended to give an overview of the notation for the
deliverable. For a root deliverable from which other will be derived, the packaging guidance should indicate the
preferred notations. Note the plural here in that there may be several notations. The packaging guidance should
provide a synopsis of them. For derived deliverables, variability can add details to notation and they can become
more focused. The packaging guidance must account for the availability (or not) of a complete set of input work
products. Depending on the configuration tailoring on a particular engagement, all input work product may not be
available. Be aware of the purpose and governance level of the deliverable being defined when outlining notation.
Describe how the inputs are assembled into a deliverable, including what particular sections may be relevant and
what the expected state of those inputs should be.
It is often best to define formatting guidelines that apply to all deliverables on the project, and then provide
additional specific guidelines as needed. It is also best to define formatting guidelines by customizing
standard formatting guidelines that already exist.
-
Deliverable Parts: Identify the work products that will be used to construct the deliverable.
Detailing Tasks
In general, when detailing a tasks (and task steps), provide specific instructions (i.e., prescriptive text). Most text
should focus on what needs to be done to accomplish the task (or an individual step of the task). Avoid long
descriptions of motivations, reasons, and philosophy. Avoid descriptions that sell the importance of what needs to be
done or motivates the steps that need to be performed. Motivations and explanations are placed in guidance such as
concepts and supporting materials. Use guidance such as guidelines to provide detailed descriptions of how to perform
steps, or to provide steps for alternative circumstances. These motivations can be referenced or linked from the
prescriptive text.
-
Purpose: The Purpose field describes the reason for the method element. For
example, for a task:
-
Why is the task being performed?
-
When a task is defined to get a work product to a particular state, identifying the purpose of the work
product state may help to clarify why the task has been broken down as it has.
-
What is the goal of the task?
-
Main description: This field is optional for tasks if individual steps are being used. If
individual steps are not being used, the Main description should explain the execution of the task and
mention the input and output work products. Do not repeat text already stated in other fields, such as the
Brief description or the Purpose. The task details can be described using the Main description
or by including specific Steps. Guidance can be attached to provide further details about how to
perform the task.
-
Key Considerations: This field is optional for tasks. It contains useful material
that does not easily fit into any of the other sections, such as advice and guidance of a critical nature, as
well as warnings, cautions, pitfalls and dangers.
-
Alternatives: This field describes different ways to accomplish the task that could be
chosen. This field is not really used any more. It is recommended that you leave it blank.
-
Steps: Steps can be specified to provide a more detailed set of instructions for the
practitioner on to how to complete the task. Tasks can be defined by providing:
-
A Main description and no Steps
-
Steps and no Main description
-
A summary or overview of the steps in the Main description, along with specific Steps.
A Step is described using:
-
Name: This is the brief description of the step.
-
Description: This optional field provides more detail for the specific step.
Writing Tasks
Provide specific instructions – prescriptive text – to perform tasks, activities, and road maps. Most text should focus
on what needs to be done to accomplish the step. Avoid long descriptions of motivations, reasons, and philosophy.
Focusing on "what to do" in tasks, activities, and road maps. Avoid descriptions that sell the importance of what needs
to be done or motivates the steps that need to be performed. Motivations and explanations are placed in guidances such
as concepts and supporting materials. Use guidances such as guidelines to provide detailed descriptions of how to
perform steps, or to provide steps for alternative circumstances. These motivations can be referenced or linked from
the prescriptive text.
When writing steps for tasks, activities, and road maps focus on:
-
The steps that need to be performed
-
The conditions or states that need to be achieved
-
Environmental issues that may need to be overcome
This information could also be maintained and referenced in a separate plug-in. For example, a Globally Distributed
Team plug-in could be created that contains the required guidance. Tasks could be extended through the contribution
mechanism to reference the guidelines in the plug-in.
Prescriptive text examples
This is an example of a single step in a task. At first glance it appears prescriptive:
Step: Determine Architectural Impact
For each change request, the Architect examines the product architecture and determines if an architectural change
needs to be made. The architecture must be clearly defined to perform this step. Usually, the architecture has been
defined and implemented in the Elaboration iteration of a previous development cycle. If a Software Architecture
Document doesn't exist it may be necessary to reverse- engineer the architecture so this task can be performed. The
time taken to reverse-engineer the architecture can be attributed to perfective maintenance. Acquiring a clear
description of the architecture extends the maintainable life of a software system.
Look for behavioral and structural changes such as:
-
Architecturally significant flows that must be changed.
-
Critical interfaces that must be re-implemented.
-
New interfaces that must be created that will be utilized by a significant percentage of the system.
-
Important data transformations that are added, removed, or need to be moved to another part of the system.
-
New generalization dependencies that may be required.
-
Generalization dependences that will disappear, for example a parent-child relationship that will be removed
when a new pattern is applied.
-
Operation signature changes that occur on heavily used interfaces.
-
Upgrades to non-functional aspects of the system (performance, security, usability, etc)
-
System interface changes that cause other system components to change
Analysis
-
"For each change request, the Architect examines the product architecture and determines if an architectural change
needs to be made." What the architect really does is "determine if an architectural change needs to be made". The
text "examines the product architecture" is vague and doesn't really add much for a seasoned practitioner. If there
is a technique to be applied, it belongs in a guideline.
-
"The architecture must be clearly defined to perform this step." This doesn't help the seasoned practitioner. It
doesn't say why the architecture wouldn't be clearly defined (presumably in the final process an architecture has
been defined), or what to do if the architecture is not clearly defined. If there is some guidance on how to deal
with architectural issues when no architectural description exists, then that should be provided in a guideline.
-
"Usually, the architecture has been defined and implemented in the Elaboration iteration of a previous development
cycle." This presumably has been done, so stating it in this step is redundant and reduces the clarity of what the
step. It also assumes a particular lifecycle is being used in the practice. Practices should avoid assuming a
particular lifecycle is being used so the practice is reusable.
-
"If a Software Architecture Document doesn't exist it may be necessary to reverse-engineer the architecture so this
task can be performed." This is another pre-requisite. It's also something that only needs to be done once so it
shouldn't be part of a step that is repeated like this one (once for each change request). It should probably be
placed in a task that's performed at the beginning of the Elaboration phase.
-
"The time taken to reverse-engineer the architecture can be attributed to perfective maintenance. Acquiring a clear
description of the architecture extends the maintainable life of a software system." This is useful motivation but
it's not prescriptive so it doesn't belong in the task step. It should be in a concept referenced from a step that
indicates when reverse-engineering should be performed.
-
"Look for behavioral and structural changes such as..." These bullet points are not about the goal of the step, and
so are good candidates for moving to a guideline.
Here's the improved step:
Step: Determine Architectural Impact
The Architect reviews each change request and determines if an architectural change is required to implement it. See
the guideline "Determining Architectural Impact" for information on how to identify changes that may have a significant
impact on the architecture.
Using the purpose, description, steps, and guidelines sections of method elements separates and simplifies text so the
reader can easily focus on the information they're interested in. Keep text sparse to allow the reader to quickly scan
and locate the information they want.
Detailing Guidance
-
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, perform a
set of steps or instantiate a particular work product.
Detailing white papers
When detailing a white paper:
-
Make sure the Brief description summarizes the white paper. The more specific the better. If it is
short, you can include the white paper's abstract
-
Attach white paper to the guidance
-
(optionally) In the Main description, you can provide more details on the white paper. If the abstract is
long, it can also be included in the Main description.
Detailing practice authoring guidance
Every practice includes the following standard guidance elements:
-
How-to-Adopt roadmap: describes 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.
-
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.
Detailing Roles
-
Key Considerations: This field contains useful material that does not easily fit
into any of the other sections, such as advice and guidance of a critical nature. as well as warnings,
cautions, pitfalls and dangers.
-
Skills: This field identifies specific skills needed to fulfill this role. List the
skills for the role in bullet form. Ensure that each bullet addresses a separate skill.
-
Assignment approaches: Enter any assignment considerations of which the delivery
practitioners should be aware. For example, this field might be used to provide advice to the project manager
running an engagement.
-
Synonyms: This field identifies alternate names for the role. Identify different terminology
an organization may have. Role names more familiar to the users of the process may be identified here. This
clarifies vocabulary and helps users of the published process clarify and transition to terminology provided in
base content.
Writing Tool Mentors
Write tool mentors with a specific goal or intent in mind. Often the best way to do this
is to tightly link the tool mentor with task steps or a guideline. Tasks describe what need to be done, and guidelines
describe how to do something. Both types of elements are goal oriented and can gain value from tool support.
Tool mentors take the perspective that the reader should use a tool to achieve a specific objective that
provides some value. This is much like the intent of a use case. Take advantage of this similarity by leveraging use
case techniques to create a tool mentor. For example:
-
Identify the tool mentor and stakeholder. Focus on what the stakeholder's objectives are. Use this
information to create the brief description.
-
Outline the tool mentor. Follow the task steps or the timeline in a guideline to help order the
outline. The reader should understand what they need to do with the tool at each step. Make sure the
reader achieves their objective by the time they reach the last step of the tool mentor.
-
Handle problems and issues that could arise. Assure the reader understands what to do if they get unexpected
results.
-
Detail the tool mentor. Include references to help text whenever appropriate. It's common to reference specific
information in the product help text at almost every step of the tool mentor.
-
Review the tool mentor and assure that it's clear how to achieve the reader's objective. The transition between the
task or guideline and the tool mentor should be clean. The reader shouldn't see anything unusual or surprising when
moving from the task/guideline to the tool mentor.
Always use a Tool Mentor guidance type to write a tool mentor. Don't add tool information directly to tasks,
guidelines, work products, etc. This keeps tooling information separate from the process content (see below).
Tool mentors and help text
Don't use tool mentors as Help Text. Help Text is shipped as part of the associated product and describes what features
do and how to use them. Tool mentors focus on achieving a goal, while Help Text describes how to use specific features
and functions of a product. Reference the help as often as necessary in the tool mentor, but don't supplement or
duplicate the help text.
Organizing tool mentor content in the library (RMC)
Categorize the tool mentors properly in the plug-ins using Standard Categories. See Guideline: Categorizing Method
Elements Using Standard Categories.
See Guideline: Tool Information in the UMF for information on placing the tool mentor content in plug-ins to
conform with UMF.
Method content is usually written to be tool agnostic. Tool mentors provide tool-specific information and are
structured so they they can be easily removed from a published configuration. This has two benefits:
-
Users can perform steps manually or add their own tooling information if they don't own IBM tools.
-
We can manage tool information independently of content so it's easier to address new features, add new tools, and
remove tools that have been end-of-lifed.
Detailing Processes
The following fields are present for all processes:
-
Purpose (optional): Describe the ultimate objective of the process. May not be needed if such
information has been included in the Brief description.
-
Main description: This is where you describe the flow of the process textually, referencing the
activities in the process, as needed.
-
Scope (optional): Describe what is included as part of the process and/or what is not.
-
Usage Notes (optional): This is especially important for capability patterns that are intended to
be used in other processes. This is where you describe how the capability pattern might be used.
-
Alternatives (optional): Describe different ways in which this process could be performed.
-
How to Staff (optional): Describe the skills you might need to execute this
process.
-
Key Considerations (optional): Describe things you might want to take into consideration when
performing this process.
The following fields are specific to delivery processes:
-
Scale (optional): The size of projects this process is intended for (e/g/. large, small, etc.)
-
Project Characteristics: Describe the types of projects the process was intended for
-
Risk Level (optional): The level of risk associated with this process.
-
Estimating Techniques: Not used. This is really something that should be tracked in a project
management tool
-
Project Member Expertise (optional): Describe the skills you might need to execute this
process.
-
Type of Contract (optional): Describe the type of contract (e.g., fixed price, time and materials,
etc.) that this process would be most appropriate for.
|