Selection of notation and modeling tool
💡 How to document and in what format is it better to convey the description?
Usually the answer to this question is related to the conditions in which your description will be "put to use." Will it be read during lunch? From a phone? Under what circumstances? How much time and attention will the description recipient have to read it?
Based on this, you can choose the format of transfer and notation.
Those who play or have played roles where the success of their descriptions directly affects income (for example, marketers) know that a poorly chosen format and notation can kill all the content, no matter how good it may be.
This is true for other descriptions as well, although less noticeable.
There are several modalities of representing descriptions and various means of creating them:
- Textual: the most universal format, with its costs because it requires attention to be concentrated on reading from left to right and top to bottom.
If text is written without markup, it quickly becomes unreadable. There are text formats with markup, with keywords, with color highlighting (syntax highlighting), with indents, and so on. The most convenient option for markup types in text is to use a double colon. First, the name of the object is written, then its type from the meta-model (or in addition, also the meta-meta-model). For example, "plane::system" or "table::system::physical object." Tools that can be used to create text are any text editors of your choice. There are text editors with syntax highlighting, and you can use syntax highlighting of the simplest languages to see only "::".
- Tabular: also one of the universal formats. It allows you to construct the header of the table (meta-model) and fill in objects (model), convenient for ontological modeling of typical objects (especially if you know how to configure many related tables in Excel, Coda.io, or similar modelers). Each object has properties (written in the table header) and the objects-instances themselves are listed in the rows. Objects of any level of the model can be modeled in tabular form.
- Graph: (not necessarily a visual representation in the form of a graph, but an approach in which objects are connected by an arbitrary number of links). This is supported by specialized ontological modelers. In them, you can also create your objects, inherit properties, and so on. In these modelers, type checking is often implemented --- what can be linked with what and how, to remove this need from the ontology. This sets them apart from diagram drawing tools. Usually in specialized modelers, there is also export to text and tabular formats by flattening the object structure.
💡 In the end: in reality, when you receive a request for a description indicating what needs to be described, you need to guess what language, how detailed and how specific you need to compose the description, how to document it and how to convey it.
And this often needs to be done quickly, with attempts often limited.
If you have never paid attention to this process, it happens automatically and, most likely, does not always yield the desired result.
We will pull it out, adjust, sharpen it, and put it back in --- let it work as it should.