Documentation

It's important to have a good and up to date documentation for the Collaboration Manager. Documentation is an accessible way to share knowledge for developers, administrators and users. It can also be used by support teams to resolve issues more efficiently.

Development Setup

Navigate to the docs folder from the command line. Executing the command make install followed by make serve will build and host the documentation for viewing locally in a browser at http://127.0.0.1:8081/. This live preview of the documentation automatically refreshes to reflect any changes made to its source files until the make serve process is terminated.

Style guide

Titles

When writing the documentation we are using title case in the Chicago Manual of Style. In addition personal names/ names of packages are written according to their documentation.

Cross-linking between pages

When referencing other pages in the documentation, use relative links to the corresponding .md file. MkDocs will resolve the link.

Warning

Do not use absolute links to other .md files in the same documentation, those will break the links when the documentation is built.

Move documentation files

When moving documentation files, add a redirect from the old location to the new location. This will prevent any pre-existing links still pointing to the old direction from breaking. This can be done by adding a line to the mkdocs.yml file:

plugins:
  - redirects:
      redirect_maps:
        'path/to/old/template.md': 'path/to/new/template.md' # Reason for the move

Tree structure

The documentation is split into four main sections, each with its own subsections:

Path	Name	Description
/user	User documentation	For users of the Collaboration Manager. It contains information about how to use the platform and its features. The content should be written in a way that it is understandable for non-technical users.
/user/project	Project documentation	This section shall describe how to create, update and delete projects. It also contains information about the project settings and the project access management, as well as backup pipelines, tool models, diagram cache model sources and the model complexity badge.
/user/sessions	Sessions documentation	Describes tool-independent session features. It contains information how to create persistent and read-only sessions.
/user/tools	Tools documentation	Tool-specific content belongs here. Examples include Capella-related topics such as workflows for TeamForCapella and Git. Jupyter, Papyrus and `pure::variants` configurations should also be documented here.
/api	API documentation	This section describes the external Collaboration Manager API usage.
/admin	Administrator documentation	For System administrators and businesses, who are interested in administering their own instances.
/development	Development documentation	For developers who want to contribute to the Collaboration Manager. It contains information about the development setup, the architecture and the code style.