Having a Model documentation

Modeling
1

Hello.

Occasionally, I’m asking myself how to document the idea, the functions and the meaning of several parts of a document model for other users (Developer, Modellers). For example, I observed that “a solution to a problem” usally leads to a convention which some people know about. But this knowledge may shift away and especially the “original problem” may be lost. Or, people in the same project take over a different part they have no knowledge of.

So my question is: Are there examples or recommendations (or a standard) to document decisions, needs, and solutions in a project which lead to a given solution coded in a Document Model.

Possible questions which the document could answer:

  • How the model is created, edited and can be maintained? When, what to be careful about?
  • What is the technical meaning of something (Annotation, Groups, Includes, …)
  • What is the “subject” meaning of something (in german “die fachliche Bedeutung”). Where is it used?
  • “Design Rules” like lowercase Field- or Groupnames, use of project-specific language (like coding rules)

I wonder how other projects approach this problem.

Kind Regards,
Stefan

2

Hi @stefan-cached-grove

Super interesting question, I look forward to the discussion.

Here are a few links from the A12 documentation so you can see what A12 provides out of the box.

  1. The model should be created, edited and maintained in the SME so that you have full modeling support. You should however take care as changes to the model, for example changing a Field Name, can necessitate a database migration. Model Versioning can be handled using, for example, git, and there is a function to compare models in the SME so that unwanted changes can be avoided. See here.

    Simple_Model_Editor_VwvaCaBumR
    Simple_Model_Editor_VwvaCaBumR1920×1160 53.8 KB

  2. The technical meaning of something can be documented in the internal description. This can be added to Groups, Fields, Includes, Rules and Attachments. You can then search for this description using the Global Search in the SME. See here.

    Simple_Model_Editor_UXKi0Jna4l
    Simple_Model_Editor_UXKi0Jna4l1920×1160 123 KB

  3. In my opinion, the “subject” meaning should be clear based on the Names given to elements in the SME. The models are designed to be readable by trained SME users and I would always recommend using the “subject” meaning in the Element Name so that it is readable in the Model Tree or Path.

  4. We recommend “Design Rules” and have used them consistently in the installer workspaces. See here.