1 Concepts | 3 Basic Structures of the MSR Application Profile |
When starting a new document, first the <report-head> (see Chapter 2.1, report-head) has to be filled with all the meta information, interjectionally stuff etc. The actual document is entered in <report-body> which receives <changes> (see Chapter 2.4.1, change objects) as the last chapter. This is the place to support the revision planning and change management. <report-rear> (Chapter 2.5, report rear) receives all the appendices.
<report-subject> allows to specify the subject of the document:
<companies> allows to enter all the information about the related companies, their team members etc. This element is taken from MSRDOC.DTD as is.
The persons involved in the document related project are listed as <team-member> within their <company>. Each <team-member> has a <role> in the process for example project-leader expert secretary supervisor etc.
If the document is mainly maintained by one person in a task force, the task force could be treated as an organization of its own behalf and entered as the only company. In this case, the native organization of the team members can be entered into <department> like the following example:
<department>Robert Bosch GmbH, K3/EES4</department>
Usually, <general-product-data> is filled with <na>. If MSRREP.DTD is used for accompanying reports in a certain project context, <general-product-data> could be used to add project related information. For further details, see Concepts of the MSR-DOC.DTD, Pos. The basic operating model
<abstract> can be used to give a short overview of the document. The contents of this element is bound to be transmitted to a document management system of a document catalog. So it should not have more than a few hundred words. In order to provide a unified content model, <abstract> can get all the paragraph level elements. But these means should be used with great care.
<chapter> in <report-head> can be used to enter excessive forewords, meta information etc. In order to provide a unified content model, there is no restriction here. Nevertheless, it is recommended not to enter the entire document at this place. For more details about <chapter> see Chapter 3.1.1, Chapter.
<admin-data> is used to markup document adminstrative data (see Figure 1, MSRREP.DTD and administrative data) such as revisions etc. The operating model is
The document (or the fragment) is handled in all companies participating in the project.
The data management in the various companies is different. For that reason, echa participant can enter information about their document management facilities in <company-doc-info>:
If a new release of the document or the fragment is given, each participating site may use a specific scheme for revision numbers. For that reason, each <doc-revision> can receive <company-revision-info> which holds the participiant specific information for the actual document revision.
It is up to a semantical check utility to keep sure that there is only one entry per company.
nevertheless, the actual revision is initiated by one individual denoted by <team-member-ref> at one certain point of time denoted by <date>.
Finally the modifications made in that revision are stored in <modifcations> where the actual <change> as well as the <reason> for that change is notified. If possible, the change can be located by <xref>.
For each <modifcation> the attribute [type] determines, if the change is made to the document only (doc-related) or to the subject of the document (part-related).
<report-body> receives an unlimited amount of <chapter>s or <chg-chapter>s, which receive the actual information.
Change manangement support is provided using <changes> which is placed into <chg-chapter>. This allows to maintain multiple change mananagements within one document.
Figure 2: | Change management support | (crpchg.wmf) |
This feature is based on the following model:
Within one document, there are several <chg-objects> to be considered in the actual project domain. These objects can be any deliverable in the process, either documents, products or even libraries.
These objects exist in multiple revisions (<chg-object-revisions>)within the process.
Requested changes can be captured and attached to these <chg-object-revision>s.
The treatment of the requested changes can be managed using element in <chg-treatment>.
Within one document, there are several <chg-objects> to be considered in the actual project domain. These objects can be any deliverable in the process, either documents, products or even libraries.
The development of <chg-object> takes place by creating new revisions. These <chg-object-revision>s are characteriezed by
The <chg-object-revision>s are referred to from within <chg-request>. This allows to generate <chg-object-revision> related tables and lists.
It is recommended not only to capture existing revisions but also future ones. This allows to refer them in order to receive complente release notes etc.
In the project there are any requested changes <chg-requests>. For each <chg-request> there is one or more related objects resp. object revisions (<chg-object-revision-ref>). The referred objects are the ones to be improved resp. causing the problem to be solved by the required change2. Thus no <chg-request> can be there without respect to a <chg-object-revision>. If necessary a fake <chg-object-revision> should be introduced.
For each <chg-request> the following can be entered:
The treatment of the reuqested changes can be documented in <chg-treatment>.
Figure 3: | Change treatment | (crpctmt.wmf) |
The treatment of one change request is expected in following steps:
The request goes through a life cycle which is documented in <chg-state>. This element receives some notes about the next actions as well as a formal state using the attribute [state] with the selection of open, in-progress, passed, rejected or done:
If there are change requests related to the actual one, this can be documented using <chg-related-requests> and <chg-request-ref>. It is possible to express if the related change is a prerequisite to the actual one. Further informatione about the relationship can be entered as text in <chg-request-ref>.
For the <chg-request> the responsibility is specified in (<chg-responsibility>). The assignment is done verbally using <desc> or as a set of <team-member-ref>s in <chg-responsible>. The latter style is treated formally and can be used to generate task lists for team members.
The possible solutions to the problem can be documented in <chg-solution> where each option can be specifed in <chg-solution-spec> and discussed using <chg-solution-pro> <chg-chg-solution-con>.
Also the estimated effort can be assinged using <chg-effort>. This is treated as a single value. It is up to the user to decide if the effort is measured in hours, days, weeks or months. Since a SGML processing system can sumarize the effort, it is recommended to use the same units.
Finally there should be a conclusion, documented in <chg-conclusion> with the following aspects:
<report-rear> receives a number of <chapter>. SGML formatting systems can add additional chapters like crossreference indexes or reports generated for <tt>.
1 Concepts | 3 Basic Structures of the MSR Application Profile |