External and embedded documents
Some documents, like MS Office or Libre-office documents, can be embedded in Modelio, in which case they become internal documentation items. They are stored and CMS managed with the model. From this point of view they become comparable to notes.
Modelio also supports external documents for which only a reference to the outside document is kept in the model, with the main advantage to not grow the model repository as the document contents is not stored by Modelio.
The following table summarizes the main characteristics of both kind of documents:
Embedded document | External document | |
---|---|---|
Storage |
Document contents stored in the CMS repository |
Document contents stored on any accessible server. Modelio only stores a reference to the document. |
SVN support |
Full support. Documents must be locked prior to any modification, they have to be committed and so on |
No CMS support. |
Format |
Only a few formats are supported: MS Office, Libre Office. |
Any format. Storing a reference is format agnostic. |
Direct edition in Modelio |
Yes, for supported formats. |
No. |
Content preview in Modelio |
Yes for some formats. |
Yes for some formats. Modelio also indicates the accessibility of the document. |
Documents can be consulted or edited outside Modelio |
No. Using Modelio is mandatory. |
Totally open. |
Notes versus documents
Choosing between a Note or a Document to describe or specify a model element is important as both solutions have pros and cons to consider.
Please remember that, if a note is always an internal documentation item, a document can be either embedded or external.
The following table compares some pro and cons of notes, embedded documents and external documents.
Documentation item type | Pro | Con | Remarks |
---|---|---|---|
Note |
|
|
|
Embedded document |
|
|
+ |
External document |
|
|
|
Direct and relative diagrams
Diagrams are an efficient documentation item for a model element. However a model element may appear in several diagrams, each of which is more or less dedicated to a part of the model or a particular aspect of the design.
Sometimes, the diagram documenting an element belongs to this element, such a diagram is called a direct diagram. Other diagrams where a model element appears are said to be relative diagrams for this element.
The Modelio Document View actually lists both direct and relative diagrams. Should you need to know more about a particular model element, just select it and the Document View will list all the diagrams owned by the element along with all the diagrams where the element is visible. If the listed diagrams are smartly named you can immediately make out which diagrams are relevant to your needs. Obviously, the Document View allows the user to open a diagram by a double-clicking on it in the document list.