- Customer request: implement project documentation as a table in MS Word
- On the path to your own project documentation
- Step 1: Document template for the standard port
- Step 2: Document relationship for realize relationships
- Step 3: Document templates for the uses relationships
- Step 4: A document template for a BlockInterface
- Step 5: A document template for a package
- Use the document templates for your product documentation
If you know objectiF RM, then you know that requirements models are not just presented as images in Word. You can also easily take over your contents, prepared individually. Behind this fact there is a generation mechanism that is customizable in many ways. Once familiar with it, this mechanism offers every user a variety of possibilities for goal-group-orientated project documentation – just by clicking a button.
Our standard template already delivers documents and document templates for your project documentation. But it’s Murphy’s law that just what you want isn’t there. That’s what happened to one of our customers: he uses SysML block diagrams, an expansion of UML, in order to specify aspects of architecture. In block diagrams he modelled interfaces that each had a use and realize relationship to blocks via a standard port. It looked something like this:
Customer request: implement project documentation as a table in MS Word
In his Word documentation, the customer now wants a table that presents an interface with its relationships and the blocks as one unit. The table entry for an interface should be automatically generated from the model and built like this:
A look at the available document templates didn’t help him much at this point. What did help him was sending an email to us, at email@example.com :-)
We could tell him: this sort of product documentation can be generated with objectiF RM. However, we have here a bit of a special case: data from different model elements has to be identified and collected together in a table. The documentation technique of objectiF RM is also recommended for such project documentation because it is very flexibly and universally implementable. Document templates can be connected and nested together – and, if required, be used again.
For the example above I will now describe, in great detail, so that you can click along with me, what has to be done (once) so that you can get the results you want at the click of a button from now on! If you are an objectiF RM user, you can just design your own project documentation.
On the path to your own project documentation
This is how it goes: you need more document templates that you can build together later. In order to make them, there are five steps you need to take (it sounds more complicated than it is, because the steps repeat themselves sometimes)
- A document template that shows the name of the block for a standard port. (it will be needed to show the name of the cells below in the desired table – see above)
- A document template for the realize relationships (left cell below, this requires point 1)
- A document template for the use relationships (right cell below, this requires point 1)
- A document template for a BlockInterface, which uses both the above templates – points 2 and 3 – for the whole upper table
- A document template for a package which uses the template from step 4 (a list of all the BlockInterfaces of a package, so a list of tables).
Step 1: Document template for the standard port
Create a new document template in your system under document templates. Select a suitable name. Select«StandardPort» as the stereotype:
Edit the document template: only the block name should be entered. Select Block.Name under the properties in the text mark area, above on the right. Then click on add. The document should then look like this:
Save the document and close Word.
Step 2: Document relationship for realize relationships
Create a new template in your system. Select a suitable name. Select «StandardPortRealizesRelationship» as the stereotype.
Edit the document template: Add the text “via the port” Then click in front of this text and select the property ParentStandardPort under properties and as the document template the template created in step one. Then click add. Now click after the text and and select in the text marking area the property ParentStandardPort.Name. Click on add again. The document should now look like this:
This text will be used later for the realize relationships in your table, in the lower left cell. Save the document and close Word.
Step 3: Document templates for the uses relationships
You already know what to do: create a new document template in your system. Choose an appropriate name. Select «StandardPortUsesRelationship» as the stereotype this time.
Edit this document template: add the text ‘via the port’-Then click in front of this text and select on the right of the text marking area the property ParentStandardPort and as the document template the document you defined in step 1. Click on the add button and then click after the text and select the property ParentStandardPort.Name. Click on add again. The document should now look like this:
This text will be the text for the uses relationships in your table the automatically generated area of the lower right cells. Save the document and close Word.
Step 4: A document template for a BlockInterface
Now the table will be assembled: create a new document template in your system. Select a name. Select «BlockInterface» as the stereotype.
Edit the document template: Add the desired table for a block interface (one column, three rows, last row divided) into two cells. Click on the first row and select the property name on the right in the text marking area. Click add. Then click in the cell of the second row and select the property description. Then click add. In the left cell of the third row of the table, enter “elements being realized”. In the next row of the same cell select on the right the listing “StandardPortRealizesRelationships” and as the document template add the template created in step 2. Cick on add. In the right cell of the third row of the table enter “element being used”. In the next row of the same cell select on the right in the text marking area under the list “StandardPortUsesRelationships” and as the document template enter the document template that was defined in step 2. The document should now look like this:
Of course, you can also add further formatting preferences if you like. We will do without them in our template. Save the document and close Word.
This document template can now be used to present all of a package’s block interfaces in the documentation in the form of a table:
Step 5: A document template for a package
Create a new document template in your system. Select a suitable name. As the stereotype, select «Package».
Edit the document template: Add your desired text as the heading of the package, Select “Name” for the name in the text marking area. Then click on add. After the empty row, select in the next row in the text marking area “BlockInterfaces” for the stereotype and the document template from step 4 for the document template. Click on Add again. The document should now look like this:
Save the document, close word – now you have defined all the necessary templates.
Use the document templates for your product documentation
Now, you can create a Word document whenever you want that uses the template from step 5 and delivers all the desired information for your project documentation together.
Then just create another document template in your system. Enter a name for the document. Select the template from step 5 as the document template. As the element to document, select the package that contains the BlockInterfaces that you want to document.
If the new document is there, select the feature “generate” from your context menu and open it. Now a table with the desired contents will be automatically generated into the table.
The results will look like this:
If there were multiple BlockInterfaces in the package, then they will be listed on top of each other. The document is limited at the moment to the graphic model from image 1.
And there you go! Maybe you have similar questions regarding your own models and you want to try this out with your own documentation. We are excited for your results!