1 Concepts 3 Basic Structures of the MSR Application Profile

2 User guide

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.

2.1 report-head

2.1.1 report-subject

<report-subject> allows to specify the subject of the document:

<overall-title>
specifies the overall environment the document belongs to. This could be the title of an overall project, an entire system, the overall title of a multipart book etc. If nothing of this matches, this element can be left out.
<main title>
specifies the major title of the document. This could be the title of a working group, the name of a subsystem, the title of a partial document etc.
<sub-title>
specifies the subtitle of the document. This could be the type of the document (e.g. user manual) etc.
<short-name>
specifies a short name under which the document is known in the project environment or the user community. This could be a mnemonic label.

2.1.2 companies

<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

2.1.3 abstract

<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.

2.1.4 chapter in report-head

<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.

2.2 admin-data

<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

2.3 report-body

<report-body> receives an unlimited amount of <chapter>s or <chg-chapter>s, which receive the actual information.

2.4 Change management support

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:

2.4.1 change objects

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

<long-name>
receiving the work title of the revision (e.g. "Summer 95 release")
<short-name>
holding the revision number
<date>
holding the release date

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.

2.4.2 chg request

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:

<long-name>
A working title for the change request. This can be used in verbal communication as well as anntoatin in overview reports
<short-name>
A label for the change request. This can be used to refer to link the document to Project Management Systems
<chg-keywords>
it is possible to enter blank separated keywords here. These can be used for retrieval purposes as well as in overview reports. It could also be used to enter notes for the project manager like assignments to indiviuals etc.
<chg-proposed-by>
can receive the names or initials of the individual(s) who proposed the change request.
<chg-priority>
Allows to qualify the priority of the requested changes. The priorization model is up to the author. The SGML processing system can use this element to order the requested changes according to their priority. Therfore the highest priority should be of low lexical order.
It can either be a simple number (high priorities get low values) determining the priority.
Another model is a letter/digit combination. The letter characterizes the importance, the digit the urgency (e.g. A 2 says very important and medium urgent)
<chg-class>
allows to classify the requested change. This element should receive something like enhancement error
<chg-related-objects>
This element receives links to the related object revidions. The semantic of this link is, that the referred object revision is causing the problem (e.g. with a bug report) or must be enhanced (in case of an enhancement request). All objects concerned by the change request should be mentioned.
<chg-subject>
This is the place to describe all the aspects of the change request. All paragraph level elements can be used.
<chg-reason>
This element receives the justification of the change request. In this element all problems should be mentioned which shall be solved by the requested change.

2.4.3 chg treatment

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:

2.5 report rear

<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