Documentation

From pyswarm

Contents 1 Different sets 1.1 Project documentation 1.2 Administrators 1.3 End-users 1.4 API specification 2 Output formats 3 Writing the documentation 3.1 Automatic generation 3.2 Taboo doc 3.3 Example of DocBook/XMI output 3.4 Documentation-related stereotypes

Different sets

Different sets of documentation for different target groups can be generated:

• Administrator documentation
• End-user documentation
• API documentation
• Project documentation (requirement engineering)

Project documentation

It seems to be smart to have requirement engineering tied somehow to the final software product documentation. Beside any project management related documentation, I think that it does make sense to use one source for documentation (actually just the UML model) and to produce the different sets and formats of documentation. However, requirement engineering will often use information (e.g. examples of typical business documents) that are not needed for the final software product, hence some of those documents are rendered obsolete by the new software, but many more reasons may justify to have additional information outside the final documentation that is generated by pyswarm SDK.

However, generally the core requirement description should be represented by the complete documentation that is generated. Of course in development phase of the project the involved persons should be able to add TODO and FIXME in any part of the documentation.

Administrators

This documentation set will help administrators to install, configure and maintain an application. Usually it covers any customization that do not require any model modifications or hacking code (for this the project documentation would be better).

End-users

Depending on the application roles (Actors specified in the UML model) customized documentation may be generated that can be used alternatively to a complete set of documentation (covering entirely all included components of the application as known from many standard software products). This documentation would also cover business processes and instruction on how to work with the GUI.

API specification

API, usually necessary for 3rd party applications that are to be integrated with a pyswarm-based application. E.g. a web-site or a legacy system.

Output formats

The pyswarm SDK will create a DocBook/XMI formatted output, optionally with related resources such as PNG or EPS files. These DocBook/XMI files than can be transformed in many other formats, depending on the tools used. (pyswarm SDK does not include such tool)

• ===XHTML 1.0 (single page)===
• ===XHTML 1.0 (chunk pages)===
• ===PDF===
• ===Microsoft Windows Help===

NOTE: PDF is created by some tools with an intermediate DocBook->LaTeX transformation step and then LaTeX->PDF.

Writing the documentation

Source: UML / XMI 2.1
The UML model can include DocBook/XML files in multiple ways. I have tried to support those ways that are already familiar from other parts of pyswarm, UML and DocBook.

Automatic generation

By default pyswarm SDK will be able to generate automatically the entire documentation out of the UML model. Of course details that are neither specified in UML nor added as comments in the model will not appear in the generated documentation. The structure of the output is not totally clear yet, but it may look something like:

1. <bookset> for the entire project (= system)
2. <book> for a specific target group
3. <part> for each particular sub-system
4. <chapter> for each domain component
5. <sect1> for each domain class

In each of those levels a more detailed structure may apply, e.g. to show all use-cases of a component or sub-system sorted by actors, attributes of a class, state machines a.s.o.

Taboo doc

Each model element can be stereotyped with pyswarm.docbook and tagged like dbFile = myplaindoc.xml (this works like the taboo source code insertion). Optionally tag with something like dbID myapp-chap1-overview to relate to a specific DocBook element instead of the entire DocBook file. The SDK will incorporate this referenced DocBook file or element instead of generating automatically the documentation for the tagged model element.

An additional approach is to use the UML comment element. All important UML model element have a description/documentation property that can be used to add information to this element. Text is provided plain. The SDK will transform the plain text into DocBook-style format, e.g. double line-breaks result in paragraphs, so <para>My first paragraph</para><para>my next paragraph</para>. Any italic will become <emphasis role="italic">italic</emphasis>, and any bold to <emphasis role="bold">bold</emphasis>.

This works with comment elements, too and these elements can even be nested if needed.

Example of DocBook/XMI output

Here an example that may result from some description for a domain class Foo or an operation or attribute.

Its first level includes the following contained doc elements which are specified in the UML model:

1. A comment with two paragraphs (In the UML tool do two line breaks between paragraphs)
2. A comment stereotyped as a Note with a title, one paragraph of text;

and nested into this comment another comment stereotyped as Important with one paragraph of text (but no title)

1. A comment stereotyped as Tip (not title, just one paragraph of text)
2. A comment with only one paragraph

And this would be the DocBook/XMI output of the model:

<para>
  My first paragraph
</para>

<para>
  the next one
</para>

<note>
  <title>
    A title for the note
  </title>
  <para>
    Here the note written into the UML model
  </para>
  <important>
    <para>
      Nest comments in the model if you want to!
    </para>
  </important>
</note>

<tip>
  <para>
    Did you know it's not a disc world?
  </para>
</tip>

<para>
  One more paragraph
</para>

Documentation-related stereotypes

Any annotated element can be stereotyped in a way they can be utilized in DocBook. DocBook itself supports these elements for this purpose: Note, Tip, Important, Warning, Caution. DocBook does not indicate which concrete meaning these elements may have in a custom document, but I suggest some kind of convention in pyswarm projects. Here the stereotypes and the suggested indication:

• pyswarm.doc.caution

Stereotype for documentation elements that may relate to any severe risk for humans or animals or life-critical systems.

• pyswarm.doc.warning

Stereotype for documentation elements that may relate to any severe risk for mission-critical systems (e.g. system failures) or may result in value reduction of assets, e.g. loss of important data.

• pyswarm.doc.important

Stereotype for documentation elements that provide important instructions for the reader.

• pyswarm.doc.tip

Stereotype for documentation elements that provide optional information or instruction for a reader that may help to save time or to improve the outcome of a given task.

• pyswarm.doc.note

Stereotype for documentation elements that provide a reader with useful background information or further details on a topic, but all of those are of less importance and usually are just optional.

All title tags are optional.

Furthermore the pyswarm.doc.example stereotype is used to specify examples in the documentation. If the title tag is not used pyswarm SDK will transform this UML element into an DocBook's InformalExample element instead of Example.