Xuse User Guide: Common Concepts
Within Xuse common concepts are used throughout the model XML files. These are described below.
Annotations
Annotations are similar in concept as annotations in MS Word documents. They can be used however you like, but are typically expected to capture thoughts that need to be revisited, inline review comments, outstanding issues or for internal team communication that should not be part of formal documentation.
Unlike MS Word annotations cannot be attached to any text, however they are used fairly extensively within the data model and can thus be associated with requirements, use-cases, use-case steps etc. The image below shows a typical annotation in XML.
Annotation is normally displayed on right hand side of the associated item in similar way to MS Word.
Note: In general annotations are likely to become more sophisticated in future versions of Xuse.
Annotation XML reference
The following table explains the XML structure for an annotation.
| Location/XPath | Cdn. | Description |
|---|---|---|
| [root-path]/xuse:annotation | 1 | Container element for the annotation. |
| [root-path]/xuse:annotation/xuse:description | 1 | Description text for the annotation. |
| [root-path]/xuse:annotation/xuse:author. | 1 | Author that created the annotation. |
| [root-path]/xuse:annotation/xuse:intended-audience | 1 | Who the annotation is intended to be viewed by. Permissible values are:
|
| [root-path]/xuse:annotation/xuse:creation-date | 0..1 | Date the annotation was created in the xs:date format. |
| [root-path]/xuse:annotation/xuse:comments | 0..1 | Container element for one or more (response) comments associated with this annotation. |
| [root-path]/xuse:annotation/xuse:comments/xuse:comment | 1..* | Container element for a (response) comment associated with this annotation. As the discussion around the original annotation progresses there may be many of these blocks. |
| [root-path]/xuse:annotation/xuse:comments/xuse:comment/xuse:description | 1 | Description text for the response. Typically useful where the original annotation raised a query. |
| [root-path]/xuse:annotation/xuse:comments/xuse:comment/xuse:comment-author | 0..1 | Name of the author of the response. |
| [root-path]/xuse:annotation/xuse:comments/xuse:comment/xuse:comment-date | 0..1 | Name of the author of the response. |
Description-text
Description text is used in many places within Xuse. This is a fairly flexible construct that allows normal text to be inter-woven with cross-references to requirements and use-cases.
An example XML fragment is shown below showing how to link to specific requirements. This is particularly useful for Use-case steps.
This is rendered as:
This example shows how to link a another use-case. Note: the container element for description text is not always <xuse:description/>.
This is rendered as:
Description text XML reference
The following table explains the XML structure for a description.
| Location/XPath | Cdn. | Description |
|---|---|---|
| [root-path]/text() | 0..* | The description XML Schema type is a mixed typed meaning that text and structure can be freely mixed together. |
| [root-path]/xuse:req-ref/@refId | 0..* | Link to a requirement. Note the HTML will link to the requirement, however the link text will be the text contained within the <xuse:req-ref/> element. If no such text is provided the title of the requirement will be shown as the link text. In other words both the following forms of link are allowed:
|
| [root-path]/xuse:uc-ref/@refId | 0..* | Link to a use-case. Note the HTML will link to the use-case, however the link text will be the text contained within the <xuse:uc-ref/> element. If no such text is provided the name of the use-case will be shown as the link text. In other words both the following forms are valid:
|
