Example: Forest documentation of the Forest prototype
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE system PUBLIC 'forest.dtd' 'forest.dtd'>
<system name='Forest' abstract='false' location='' standalone='false' status='Development' >
<title>
The Forest System
</title>
<motivation>
Many companies are having difficulties with creating and maintaining proper documentation of the systems they build. The Forest project proposes a new method and a set of tools to improve the way of creating and maintaining documentation.
</motivation>
<description>
The Forest system is indended to create and maintain documentation of any system, e.g. a software system. Documents are created using a Document Generator component. Requirements traceability verifies that requirements are actually implemented. Performing (traceability) checks is done by the Model Checker component. An overview of the components of the current Forest prototype implementation is shown below.<img src='images/forest_components.png' title='Components of the Forest prototype' scale='50.0' />
</description>
<requirement name='generate documentation' stakeholder='everyone' type='Functional' priority='Must' >
<title>
Documentation generation from the repository
</title>
<description>
It should be possible to generate documentation based on the information in the repository. The user should be able to select a document template and a layout template.
</description>
<requirement name='readable by anyone' stakeholder='everyone' type='Non_functional' priority='Must' >
<title>
All documentation should be readable by anyone
</title>
<description>
Both the repository contents and the documents generated from those contents should be readable by anyone.
</description>
</requirement>
<requirement name='dynamic-personalized requirements' stakeholder='' type='Business' priority='Must' >
<title>
Generated documents should be dynamic and personalized
</title>
<description>
Documents should be generated on-the-fly (dynamic), an contain information that is of interest to the respective stakeholder.That is, a requirements engineer may generate a requirements document. Furthermore, the level of abstraction of artefactsthat should appear in the documentation should be configurable, as well as the part of the system for which a document is being created.
</description>
</requirement>
</requirement>
<requirement name='easy includable core' stakeholder='project leader' type='Constraint' priority='Must' >
<title>
Easy include core in (new) tools
</title>
<description>
The repository and the checker should be built without external dependencies. This should allow for easy including in current and future tooling.
</description>
</requirement>
<requirement name='readable repository' stakeholder='' type='Non_functional' priority='Must' >
<title>
The repository should be readable
</title>
<description>
Other tools should be able to read/write from/to the repository
</description>
</requirement>
<requirement name='document any sys' stakeholder='' type='Functional' priority='Must' >
<title>
Document any system
</title>
<description>
The prototype should (just like the entire Forest method) not be intended only for documenting software systems, but should rather be usable for documenting any system.
</description>
</requirement>
<requirement name='easy to use' stakeholder='' type='Non_functional' priority='Must' >
<title>
Easy to use
</title>
<description>
The user should be able to fill in as much or as little information as he likes. There should be no blocking error messages or dialog screens that enforce the user to enter more information or invest more time at a certain moment.
</description>
</requirement>
<requirement name='low threshold' stakeholder='' type='Constraint' priority='Must' >
<title>
Low threshold
</title>
<description>
It should be very little work to define the structure of a system in terms of subsystems.
</description>
</requirement>
<requirement name='central repository' stakeholder='all' type='Functional' priority='Must' >
<title>
Central repository
</title>
<description>
A central repository should be used to store all information artefacts.
</description>
<requirement name='requirements traceability' stakeholder='trace engineer' type='Functional' priority='Must' >
<title>
Automated consistency checking and requirements traceability
</title>
<description>
It should be possible to trace all requirements to their implementation. If an implementation of acertain requirement can not be found, and not all subrequirements are implemented, an error added to the repository. When creating documentation, thiserror can be made visible in the generated document.
</description>
</requirement>
</requirement>
<requirement name='open and extendable' stakeholder='' type='Functional' priority='Must' >
<title>
Open and extendable
</title>
<description>
Anyone should be able to build tools and extensions for a Forest repository, and the format should still be readable in the future.
</description>
</requirement>
<requirement name='IDE integration' stakeholder='end user' type='Non_functional' priority='Must' >
<title>
Integrated with IDE
</title>
<description>
An advantage in efficiency is expected when documentation is properly integrated with the development environment used by a developer. Documentation, or implementation artefacts, should be found faster because of extra navigation possibilities between implementation and documentation.
</description>
</requirement>
<requirement name='support for re-use' stakeholder='' type='Functional' priority='Must' >
<title>
Support for re-use
</title>
<description>
Artefacts should be markable as reusable, and be re-used several times.
</description>
</requirement>
<requirement name='separate tools and content' stakeholder='' type='Non_functional' priority='Must' >
<title>
Separate tools and content
</title>
<description>
</description>
<requirement name='stand alone tools' stakeholder='' type='Functional' priority='Must' >
<title>
Stand alone model checker and document generator
</title>
<description>
A stand alone tool should be available to check the contents of a Forest repository and to generate documentation.
</description>
</requirement>
</requirement>
<requirement name='no code generation' stakeholder='' type='Business' priority='Must' >
<title>
Not intended for code generation
</title>
<description>
Forest is meant as a documentation supporting tool, not as a code generator
</description>
</requirement>
<delegation name='delegation standalone' >
<title>
</title>
<source ref='stand alone tools' />
<target ref='Commandline Application' />
</delegation>
<delegation name='del-traceability' >
<title>
</title>
<source ref='requirements traceability' />
<target ref='Model checker' />
</delegation>
<delegation name='del-readable' >
<title>
</title>
<source ref='readable repository' />
<source ref='open and extendable' />
<target ref='Core' />
</delegation>
<delegation name='delegation docgen' >
<title>
</title>
<source ref='dynamic-personalized requirements' />
<target ref='Document generator' />
</delegation>
<delegation name='easy includable' >
<title>
</title>
<source ref='easy includable core' />
<target ref='Core' />
</delegation>
<delegation name='easy' >
<title>
</title>
<source ref='easy to use' />
<source ref='low threshold' />
<source ref='IDE integration' />
<target ref='Eclipse plug-in' />
</delegation>
<delegation name='reuse' >
<title>
</title>
<source ref='support for re-use' />
<target ref='Core' />
</delegation>
<delegation name='central repos' >
<title>
</title>
<source ref='central repository' />
<target ref='Core' />
</delegation>
<atom name='Misc' ref='.' status='Development' >
<title>
Misc
</title>
<implements ref='document any sys' />
<implements ref='no code generation' />
<description>
TODO: where to implement these requirements?
</description>
</atom>
<system name='Commandline Application' abstract='false' location='' standalone='false' status='Development' >
<title>
Forest Application
</title>
<motivation>
</motivation>
<description>
The commandline application allows for checking the Forest Repository and generating documentation. A batch file for windows, or a shell script for Linux/Mac OS allows for easy starting the application.
</description>
<atom name='Forest Application' ref='application/Forest.java' status='Implemented' >
<implements ref='inh_stand alone tools' />
</atom>
</system>
<system name='Core' abstract='false' location='' standalone='false' status='Implemented' >
<title>
Forest Core
</title>
<description>
The Core subsystem contains the implementation of the Forest repository (the object model) and a checker that can verify that the repository is in a valid state. When buildinga tool (document generator, editor,etc.), this core package is needed.
</description>
<requirement name='java implementation' stakeholder='thkr' type='Non_functional' priority='Must' >
<title>
Java implementation needed
</title>
<description>
For building anyForest tools in Java, a Java implementation of the Forest repository is required
</description>
</requirement>
<requirement name='XML for storage' stakeholder='' type='Non_functional' priority='Must' >
<title>
Use XML to store repository
</title>
<description>
There are a number of advantages when using XML to store the repository...
</description>
</requirement>
<delegation name='delegation repos' >
<title>
</title>
<source ref='inh_central repository' />
<source ref='inh_readable repository' />
<source ref='inh_open and extendable' />
<source ref='java implementation' />
<target ref='Repository' />
</delegation>
<delegation name='delegation re-use' >
<title>
</title>
<source ref='inh_support for re-use' />
<target ref='Repository' />
</delegation>
<delegation name='delegation-repository' >
<title>
</title>
<source ref='inh_open and extendable' />
<target ref='XML for storage' />
</delegation>
<delegation name='delegation XML' >
<title>
</title>
<source ref='XML for storage' />
<target ref='Parser/Serializer' />
</delegation>
<atom name='atom Standalone' ref='core' status='Implemented' >
<title>
Standalone
</title>
<implements ref='inh_easy includable core' />
<description>
The core is not dependent on any framework, and can thus be easily included in a project.
</description>
</atom>
<system name='Repository' abstract='false' location='' standalone='false' status='Implemented' >
<title>
Forest Repository
</title>
<description>
The object model is the runtime version of the repository. It is acquired by parsing a Forest XML file (which contains a persisted repository). The Model Checker, Document Generator, or Editors work with this object model. Editors are responsible for proper serialization to XML files, when saving the modifications.
</description>
<atom name='Plain Old Java Objects' ref='core/model' status='Implemented' >
<implements ref='inh_inh_central repository' />
<implements ref='inh_java implementation' />
</atom>
<atom name='XML syntax' ref='core/serializer/XMLSerializer.java' status='Implemented' >
<title>
The repository contents are stored in an XML notation
</title>
<implements ref='inh_inh_readable repository' />
<implements ref='inh_inh_open and extendable' />
</atom>
<atom name='abstract pattern support' ref='core/model/Extension.java' status='None' >
<title>
Support for re-usable (abstract) patterns
</title>
<implements ref='inh_inh_support for re-use' />
<description>
The repository supports an abstract system declaration, which may contain requirements or designs that do not need an implementation. These abstract systems can then be extended, which effectively means the abstractly defined requirements or designs are inherited and should be implemented in the extending system.
</description>
</atom>
</system>
<system name='Model checker' abstract='false' location='' standalone='false' status='Implemented' >
<title>
Model Checker
</title>
<description>
The Model Checker component contains a number of checks to verify that the repository is in a valid state. That means, requirements should be implemented,referenced elements should exist, etc.
</description>
<requirement name='multiple checks' stakeholder='trace enigneer' type='Functional' priority='Wish' >
<title>
Multiple checks should be available
</title>
<description>
The model checker should be able to perform several checks on the repository
</description>
</requirement>
<delegation name='del-modelchecker-1' >
<title>
</title>
<source ref='multiple checks' />
<target ref='Checks' />
</delegation>
<atom name='ModelChecker' ref='core/modelchecker/ModelChecker.java' status='Implemented' >
<title>
The Model Checker
</title>
<implements ref='inh_requirements traceability' />
</atom>
<atom name='CheckDelegator' ref='core/modelchecker/CheckDelegator.java' status='Implemented' >
<title>
The Check Delegator
</title>
<implements ref='inh_requirements traceability' />
</atom>
<atom name='Checks' ref='core/modelchecker/checks' status='Implemented' >
<title>
Checks
</title>
</atom>
</system>
<system name='Parser/Serializer' abstract='false' location='' standalone='false' status='Implemented' >
<title>
Parser/Serializer
</title>
<description>
The parser takes care of instantiating the repository object model from one or more XML files. The serializer does the reverse, it stores the repository as one or more XML files in the file system.
</description>
<delegation name='delegation use XML' >
<title>
</title>
<source ref='inh_XML for storage' />
<target ref='parser' />
<target ref='serializer' />
</delegation>
<atom name='parser' ref='core/parser/handlers/ForestContentHandler.java' status='Implemented' >
<title>
Parser
</title>
<description>
The parser used in the Forest prototype is a default SAX parser implementation. Hence, the most important part is the ForestContentHandler that handles the artefacts that are parsed from the XML and creates and links objects in the object model.
</description>
</atom>
<atom name='serializer' ref='core/serializer/XMLSerializer.java' status='Implemented' >
<title>
Serializer
</title>
<description>
The serializer takes care of storing the Forest object model as one XML file.
</description>
</atom>
</system>
</system>
<system name='Document generator' abstract='false' location='' standalone='false' status='Implemented' >
<title>
Document Generator
</title>
<description>
The document generator is an existing component, called Simple Document Generator (SDG), written by Joris.The XML parser that comes with SDG is not used, the Forest Document Generator class builds the Document Model itself, based on the type of document and the information in the repository.
</description>
<atom name='PDF renderer' ref='../../../../../resources/sdg/jars/sdg-1.0.6.jar' status='Implemented' >
<implements ref='inh_readable by anyone' />
</atom>
<atom name='SDG driver' ref='documentgenerator/DocumentGenerator.java' status='Implemented' >
<title>
SDG driver
</title>
<implements ref='inh_generate documentation' />
<description>
This component creates a Document Model by selecting the desired information from the Forest object model. This Document Model is then passed to SDG to be rendered into a nice document. SDG is responsible for the output format.
</description>
</atom>
<atom name='Artefact selector' ref='' status='Implemented' >
<title>
Artefact selector
</title>
<implements ref='inh_dynamic-personalized requirements' />
<description>
A query language needs to be designed and implemented to be able to select certain information from the Forest object model. Information specific to the user's role may be selected, or e.g. only information at a high level of abstraction.
</description>
</atom>
</system>
<system name='Eclipse plug-in' abstract='false' location='' standalone='false' status='Development' >
<title>
Forest Eclipse plug-in
</title>
<description>
The Eclipse plug-in contains two prototypeeditors, that can be used for modifying the information in the Forest repository.<img src='images/eclipse.png' title='Eclipse' scale='50.0' />
</description>
<delegation name='delegation easy1' >
<title>
</title>
<source ref='inh_easy to use' />
<source ref='inh_low threshold' />
<target ref='Design editor' />
<target ref='Requirements editor' />
</delegation>
<atom name='Eclipse workbench controller' ref='eclipse/IOController.java' status='Implemented' >
<title>
Workbench I/O
</title>
<implements ref='inh_IDE integration' />
</atom>
<system name='Requirements editor' abstract='false' location='' standalone='false' status='Development' >
<title>
Requirements Editor
</title>
<description>
The Forest Requirements editor is an Eclipse editor for entering/modifying requirements
</description>
<atom name='Userfriendly req-editor UI' ref='eclipse/editors/requirements/RequirementsEditor.java' status='Implemented' >
<title>
User friendly UI
</title>
<implements ref='inh_inh_easy to use' />
<implements ref='inh_inh_low threshold' />
<description>
The user interface of the requirements editor follows the Eclipse UI guidelines and best practices
</description>
</atom>
</system>
<system name='Design editor' abstract='false' location='' standalone='false' status='Development' >
<title>
Design Editor
</title>
<description>
The design editor can be used to create a systems structural design (a system consists of subsystems, that may in turn consist of subsystems of their own). Descriptions and motivation can be entered and modified. Atoms (implementations) can be defined, and localor inherited requirements can be delegated to such an atom.<img src='images/design_editor.png' title='Forest Design Editor' scale='50.0' />
</description>
<atom name='Userfriendly design-editor UI' ref='eclipse/editors/design/DesignEditor.java' status='Implemented' >
<title>
User friendly UI
</title>
<implements ref='inh_inh_easy to use' />
<implements ref='inh_inh_low threshold' />
<description>
The user interface of the design editor follows the Eclipse UI guidelines and best practices
</description>
</atom>
</system>
</system>
</system>
Website last updated: July 11, 2007