Documentation and Comments in Diagramming

Software Ideas Modeler provides a range of features to support effective documentation, including comments, glossaries, and associated multipart documentation.

Documented Elements

One of the key features is the ability to add documentation to individual elements and fields within diagrams, to diagrams themselves, and also to folders. This documentation can be accessed in a number of ways, including through a floating window in the diagram editor, documentation sidebar, and Properties dialog.

You can easily identify all elements with documentation in the diagram - they are indicated by a small document icon in the left top corner outside documented elements. Clicking on that icon, you can open a floating window with a documentation editor.

Element documentation

To add documentation to an element in a diagram, you can also select the element and open the Properties dialog. In the Properties dialog, there is a Documentation tab where you can enter the documentation for that element. This documentation can include text, images, and links to other resources, and it can be edited at any time.

The documentation editor is also accessible from the Documentation sidebar, allowing developers to switch between documentation for a selected field, element, diagram, or folder. This way is easy to navigate and find the information they need. The tool offers also a feature that allows you to add separate documents to the project in the same way as diagrams, so you can store all the related information in one place.

Diagram Comments

Another important feature of Software Ideas Modeler is the ability to add comments to elements in diagrams. Comments can be added to any element in a diagram using the "Add Comment" button in the context bar below the selected element. Comments can be used to provide additional information or clarification about an element. Their advantage is that the can be viewed and edited at any time.

Adding a comment to a class (in a diagram editor).

Glossary

In addition to comments, Software Ideas Modeler also provides support for glossary items. Glossary items can be added by selecting "Add Glossary Item" from the context menu. They can be used to provide definitions for technical terms or another specialized vocabulary that may be used in the documentation. They are stored in a separate Glossary window, which can be accessed from the ribbon or menu.

Export Documentation

Another useful feature of Software Ideas Modeler is the ability to export documentation in a variety of formats. This includes DOCX, HTML, PDF, RTF, and TXT allowing you to create documentation that can be easily shared with others.

When to Use Comments and When Documentation

One of the main advantages of using comments in diagrams is that they provide context for the elements and relationships being represented. For example, if a diagram shows a complex system with many components, it can be difficult to understand the purpose and function of each component without additional information. Comments can help to provide this information by describing the role of each component and how it relates to the overall system.

The diagram can become cluttered and hard to read if the comments are overused. Comments are usually specific to a single diagram and element and may not provide a broader understanding of the system.

The documentation is separated from the diagram visuals, so it can be used to provide a more detailed and comprehensive understanding of the system. This can include things like design documents, requirements, and user manuals. The attached documentation offers more space for the details and can be used to provide a more global perspective on the system.

In general, it is best to use a combination of both comments and attached documentation to effectively communicate the design and intent of a software system. Comments can be used to provide context for specific elements and relationships within a diagram, while attached documentation can be used to provide a more comprehensive understanding of the system.

Tips And Tricks

• Use element documentation for providing detailed information about a specific element in a diagram, such as its properties, behavior, or interactions. This is useful for providing context and understanding for others who are reviewing or working with the diagram.
• Use comments in a diagram to provide brief notes or explanations about specific parts of the diagram. This is useful for providing quick, informal explanations that don't require a lot of detail.
• Use the glossary to create a centralized location for storing definitions and explanations for important terms and concepts related to the diagram. This is useful for providing a quick reference for people who may not be familiar with the subject matter.
• Use documentation pages for providing an overview or introduction to the diagram, as well as for grouping related diagrams together. This is useful for providing context and organization for the diagrams.
• Use element documentation, comments, and glossary in conjunction with each other. For example, element documentation can provide detailed information and a comment can provide a quick note or explanation. Use the glossary to explain the important domain terms used in the documentation and comments.