From dec143046e14d52666dfb59b06fd336f2914eecf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Annama=CC=81ria=20Koren?= Date: Mon, 16 Nov 2026 09:23:55 +0100 Subject: [PATCH 1/3] add how to use this documentation guide, CMEM-8383 - explain the sections, the four content types, where to start, search, tags and versions - link the guide from the header, the footer and the Home page --- docs/index.md | 3 + docs/introduction/.pages | 1 + .../how-to-use-this-documentation/index.md | 153 ++++++++++++++++++ nav.yml | 2 + overrides/partials/copyright.html | 3 +- overrides/partials/header.html | 10 ++ 6 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 docs/introduction/how-to-use-this-documentation/index.md diff --git a/docs/index.md b/docs/index.md index b9872d667..bbfa4e63b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -211,3 +211,6 @@ Choosing one of these roles is not required at this point. - [What is a knowledge graph?](introduction/what-is-a-knowledge-graph/index.md): the concept, 5 minutes, on the main path - [Semantic Web basics](introduction/semantic-web-basics/index.md): optional, the terminology, about 35 minutes - [eccenca Corporate Memory at a glance](introduction/corporate-memory-at-a-glance/index.md): the parts of the product and how they relate + +Lost at any point? +[How to use this documentation](introduction/how-to-use-this-documentation/index.md) explains how the documentation is organized. diff --git a/docs/introduction/.pages b/docs/introduction/.pages index 624c2d364..830616c8f 100644 --- a/docs/introduction/.pages +++ b/docs/introduction/.pages @@ -5,3 +5,4 @@ nav: - Corporate Memory at a glance: corporate-memory-at-a-glance - Highlight features: highlight-features - Get access: get-access + - How to use this documentation: how-to-use-this-documentation diff --git a/docs/introduction/how-to-use-this-documentation/index.md b/docs/introduction/how-to-use-this-documentation/index.md new file mode 100644 index 000000000..b3fa2612d --- /dev/null +++ b/docs/introduction/how-to-use-this-documentation/index.md @@ -0,0 +1,153 @@ +--- +title: "Introduction: How to use this documentation" +--- + +# How to use this documentation + +This documentation describes eccenca Corporate Memory from first contact to operation in production. +It is organized by what is being done with the product, not by the parts of the user interface. + +Reading time: 4 minutes. + +## Two ways in + +- **New to Corporate Memory**: follow the introduction on [Home](../../index.md). + It leads from what the product is for to getting access and a first tutorial. +- **Familiar with Corporate Memory**: go straight to a section in the main menu, such as **Build** or **Explore**. + Each section has an overview that lists everything it contains. + +## How the documentation is structured + +The main sections follow the path that data takes through Corporate Memory. +Each section overview names its intended audience next to :octicons-people-24:. + +| Section | What it covers | Intended audience | +| --- | --- | --- | +| :material-star: [Build](../../build/index.md) | Turning source data from files, databases, APIs and streams into a Knowledge Graph. | Linked Data Experts | +| :material-star: [Explore](../../explore-and-author/index.md) | Browsing, querying, editing and validating the Knowledge Graph. | Linked Data Experts and Domain Experts | +| :material-star: [Consume](../../consume/index.md) | Providing data from the Knowledge Graph to other applications and tools. | Linked Data Experts | +| :material-star: [Distribution](../../distribution/index.md) | Discovering, installing and managing ready-made Marketplace Packages. | All Corporate Memory users | +| :material-star-outline: [Deploy and Configure](../../deploy-and-configure/index.md) | Installing, configuring and upgrading Corporate Memory. | Deployment Engineers and System Administrators | +| :material-star-outline: [Automate](../../automate/index.md) | Scheduling workflows, continuous integration and delivery, and the `cmemc` command line client. | Linked Data Experts and Deployment Engineers | +| :material-star-outline: [Develop](../../develop/index.md) | Extending Corporate Memory with plugins and packages, and accessing it through its APIs. | Software Developers and Linked Data Experts | +| :material-calendar: [Release Notes](../../release-notes/2026/corporate-memory-26-2/index.md) | Changes and enhancements in each version. | All Corporate Memory users | + + +A filled star :material-star: marks the sections about working with data and the Knowledge Graph. +An outlined star :material-star-outline: marks the sections about operating, automating and extending Corporate Memory. + +The overviews of Build, Explore, Consume and Distribution show a diagram of the product architecture. +The highlighted area marks the part of the product the section describes. + +**Home** introduces Corporate Memory and the ideas behind it. +**Learn** collects the tutorials and the training material of all sections in one place. + +## Four types of content + +Each topic in this documentation serves one of four purposes. +In the menu of **Build**, for example, the topics are grouped by these types. + +| Type | Answers the question | Example in Build | +| --- | --- | --- | +| **Foundations** | How does it work, and why? | [Cool IRIs](../../build/cool-iris/index.md) | +| **Tutorials** | How is a complete result reached, step by step? | [Lift data from tabular data](../../build/lift-data-from-tabular-data-such-as-csv-xslx-or-database-tables/index.md) | +| **Guides** | How is a specific feature used in an existing project? | [Workflows](../../build/workflows/index.md) | +| **Reference** | What exactly does an operator, a parameter or an option do? | [Task and Operator Reference](../../build/reference/index.md) | + +Choose the type by the current goal: + +- To understand a concept before working with it, read a **Foundations** topic. +- To learn a feature by example, follow a **Tutorial** from start to finish. + A tutorial brings its own sample data and works on an empty project. +- To get a task done in an existing project, use a **Guide**. + A guide assumes that the concepts are known. +- To look up a single detail, use the **Reference**. + It is not meant to be read from top to bottom. + +### Tutorials in a section and in Learn + +The tutorials in a section focus on the features of that section. +[Learn › Tutorials](../../tutorials/index.md) lists the tutorials of all sections, grouped by level: beginner, advanced and expert. + +[Learn › Training](../../training/index.md) contains the material of the eccenca Corporate Memory training. +Its modules cover the theory behind Corporate Memory, such as RDF, SPARQL and ontology modeling, and link to the tutorials for the hands-on sessions. + +## Where to start by role + +- **Linked Data Experts and data engineers** start in [Build](../../build/index.md), with the **Foundations** and a tutorial. +- **Domain Experts and business users** start in [Explore](../../explore-and-author/index.md). +- **Software Developers** start in [Develop](../../develop/index.md). +- **Deployment Engineers and System Administrators** start in [Deploy and Configure](../../deploy-and-configure/index.md). + +## How to find a topic + +- **Search**: the search field in the header searches all sections of the selected version. + A search result opens with all occurrences of the search term highlighted. +- **Tags**: tags such as `BeginnersTutorial` group related content across sections. + The tags of a topic appear next to the breadcrumb at the top. + Select a tag to see all topics that carry it, or open the [tag index](../../tags.md). +- **Breadcrumb**: the path above each heading shows where a topic sits in the structure. + Select an entry to go up one or more levels. + +## Versions + +The documentation is published separately for each release of Corporate Memory. +The version `latest` is the documentation of the most recent release. + + +To read the documentation that matches a deployment, select its version from the version selector in the header. +The version of a deployment is shown in the user interface of Corporate Memory. + + +Features, labels and steps can differ between versions. +When the product does not match a description, check the selected version first. + +## How to read the content + +### Text formatting + +- **Bold text** marks elements of the user interface, spelled exactly as in the product, for example **Create**. +- `Monospace text` marks values to enter or select, file names and technical identifiers, for example `CMEM_BASE_URI`. + +### Boxes + +Colored boxes set information apart from the main text. + +!!! info + + Background information or context. + +!!! note + + A detail worth knowing that is not essential for the task. + +!!! tip + + A shortcut or a better way to reach the same result. + +!!! warning + + An action that can cause data loss or an unexpected result. + +!!! example + + A sample, often collapsed, such as a query or a configuration file. + +## Help inside Corporate Memory + + +Corporate Memory provides context help for the main functions of its workspaces. +Select :material-help-circle-outline: to open it. + +## When the documentation is not enough + +### Get help + + + +### Report missing or unclear content + +Each topic ends with a **Comments** area. +Use it to report a mistake, an unclear explanation or a missing topic. +Commenting requires a GitHub account. +The comments are public and are stored as discussions in the [documentation repository](https://github.com/eccenca/documentation.eccenca.com/discussions). diff --git a/nav.yml b/nav.yml index f45aaa421..91a2facc7 100644 --- a/nav.yml +++ b/nav.yml @@ -15,6 +15,8 @@ nav: - introduction/highlight-features/index.md - Get access: - introduction/get-access/index.md + - How to use this documentation: + - introduction/how-to-use-this-documentation/index.md - Build: - Build: build/index.md - Foundations: diff --git a/overrides/partials/copyright.html b/overrides/partials/copyright.html index 59d74b607..671292285 100644 --- a/overrides/partials/copyright.html +++ b/overrides/partials/copyright.html @@ -27,7 +27,8 @@ {{ config.copyright }} - CC-BY-SA-4.0 - - Imprint + Imprint - + How to use this documentation {% endif %} {% if not config.extra.generator == false %} diff --git a/overrides/partials/header.html b/overrides/partials/header.html index 8ab348264..8fb44d0dc 100644 --- a/overrides/partials/header.html +++ b/overrides/partials/header.html @@ -161,6 +161,16 @@ {% endif %} {% endif %} + + + {% include ".icons/material/compass-outline.svg" %} + +
Get a Sandbox From 6426a3264a19705fc48830834cea4faf09f67537 Mon Sep 17 00:00:00 2001 From: Rene Pietzsch Date: Fri, 20 Nov 2026 11:40:13 +0100 Subject: [PATCH 2/3] remove reading time from how to use this documentation page, CMEM-8383 --- docs/introduction/how-to-use-this-documentation/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/introduction/how-to-use-this-documentation/index.md b/docs/introduction/how-to-use-this-documentation/index.md index b3fa2612d..bde31b553 100644 --- a/docs/introduction/how-to-use-this-documentation/index.md +++ b/docs/introduction/how-to-use-this-documentation/index.md @@ -7,8 +7,6 @@ title: "Introduction: How to use this documentation" This documentation describes eccenca Corporate Memory from first contact to operation in production. It is organized by what is being done with the product, not by the parts of the user interface. -Reading time: 4 minutes. - ## Two ways in - **New to Corporate Memory**: follow the introduction on [Home](../../index.md). From 3caaa703f3c48ae4c8db9992a7485d9379eda5ac Mon Sep 17 00:00:00 2001 From: Rene Pietzsch Date: Fri, 20 Nov 2026 11:42:12 +0100 Subject: [PATCH 3/3] move how to use this documentation to the top of the introduction, CMEM-8383 --- docs/introduction/.pages | 2 +- nav.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/introduction/.pages b/docs/introduction/.pages index 830616c8f..0d2017edc 100644 --- a/docs/introduction/.pages +++ b/docs/introduction/.pages @@ -1,8 +1,8 @@ --- nav: + - How to use this documentation: how-to-use-this-documentation - "What is a knowledge graph?": what-is-a-knowledge-graph - Semantic Web basics: semantic-web-basics - Corporate Memory at a glance: corporate-memory-at-a-glance - Highlight features: highlight-features - Get access: get-access - - How to use this documentation: how-to-use-this-documentation diff --git a/nav.yml b/nav.yml index 778cca8fb..ccbd52275 100644 --- a/nav.yml +++ b/nav.yml @@ -5,6 +5,8 @@ nav: - Home: - index.md + - How to use this documentation: + - introduction/how-to-use-this-documentation/index.md - What is a knowledge graph?: - introduction/what-is-a-knowledge-graph/index.md - Semantic Web basics: @@ -15,8 +17,6 @@ nav: - introduction/highlight-features/index.md - Get access: - introduction/get-access/index.md - - How to use this documentation: - - introduction/how-to-use-this-documentation/index.md - Build: - Build: build/index.md - Foundations: