 |  |
SE^2's Cookbook for MBSE with SysML consists of two parts
- Part I: MBSE in Telescope Modeling, v147
This part is modeled in the APE model as View, conforming to the DocBook Viewpoint, and directly generated from the model
Cookbook Part I: Introdoction (pdf)
Cookbook Part I: Introduction (DocBook XML, zipped) - Cookbook Part II: Pattern, Recipes, and Best Practices issue 1 (pdf v759)
Summary
The document is modeled in the same model as the system, using UML/SysML elements.
A subset of the DocBook markup language is mapped to stereotypes, and applied to UML/SysML model elements, e.g.
chapter to package, paragraph to comment.
The MBSE plugin which you can download from this site creates a DocBook file from the model.
Note, that it is just a proof of concept with limitations. For example, only a limited number of DocBook elements are supported but
sufficient to make reasonable use of it.
The advantages are manifold
* consistent integration of system model and system documentation
* direct linking to model elements (also diagrams) from the document
* changes of diagram names is automatically reflected in the document
* using proper definition of the stereotype associations only compatible elements can be selected to compose the document, e.g.
a figure references diagrams, a chapter references paragraphs.
* the documentation is at the same time navigable in the model and printable
* documents are modeled in a tool independent way. Only a small plugin is needed to generate DocBook XML.
There are also disadvantages (which we hope will be solved by tool vendors in the future...)
* no wysiwyg (but that's a general problem. also with velocity based documentation)
* which subset of DocBook should be supported?
* creating cross-references (also internal ones) is possible but a bit cumbersome
* comments are elements without a name and therefore a bit difficult to find in the model browser
* MagicDraw's text editor supports only HTML which is not compliant with DocBook and the text has to be transformed (which is done automatically when generating)
The document is modeled in the APE project as a view (APE_Projects_Views->Cookbook->Cookbook_Content)
As DocBook viewer and toPDF transformer we used oxygen XML editor
Note: Everthing you read on this webseite or download from this website you use at or own risk and cost.
There is no warranty for correctness or completness for any item.