This DN is about how we organize and present documentation for customers of openUC2 products, and documentation for community users & developers of things in the openUC2 ecosystem.

Covered topics include:

Information hierarchy

openUC2 produces several products and also is an ecosystem of technical components & subsystems. We have a single documentation website for everything in openUC2, so that our documentation for our various coupled systems/subsystems/modules can evolve and be deployed together; and so that our documentation is easier to navigate.

Because we have so much documentation, we organize it hierarchically; here, we describe the four highest levels of this hierarchy:

  1. Usage vs. development
  2. Product lines
  3. Products
  4. Forms of documentation

We organize our content this way because we need a single entry-point for new users of each product; that entry-point should be placed alongside the information which new users need to get started, so that all of that information will be easy for new users to discover. We keep developer-oriented information very separate in order to prevent the documentation from being too overwhelming for new users. We group content at the fourth level (forms of documentation) to keep the same forms close to each other, for reasons discussed in Sequencing of documentation.

Usage vs. development documentation

To make the documentation easy for our customers to navigate, we will split our documentation site up into three overall categories: usage documentation, development documentation, and workshop plans.

Usage

Usage documentation helps our customers to use/operate our products (and their advertised built-in functionalities) off-the-shelf as end-users, but not to develop new (i.e. not built-in) functionalities with our products as developers. Examples of the kinds of topics which belong here include: