Release v0.12: Service documentation

[ademitri]

The Service Documentation feature is used to enable service providers to introduce their users to their application. This includes useful information such as functionalities or technical information required for the design, development, use or maintenance of the service.
For this, we have prepared a step-by-step guide, which is presented in the following:

Step 1 - Prerequisites

In order to be able to use the service documentation feature, the following prerequisites are required:

1. Registration to Calponia
2. Login to Provider Portal
3. Creation of an application with a first version

The Marketplace feature can then be accessed in the Provider Portal. There you will find the Documentation tab.

The following chapters explain step by step how to create and publish the content for the service documentation.

Step 2 - How to setup your repository

You can set up a repository by following these steps:

1. Go to Marketplace
2. Click on Documentation tab
3. Follow the instructions for ssh or https on the right side of the page

Step 3 - How to clone an existing repository

If you want to clone an existing repository e.g. for collaborative development of a service documentation, you can do this as follows:

git clone https://git:<TOKEN>@git.calponia-latest.de/527b2f49-10f3-49af-9994-34549d853b14--documentation.git
git checkout <branch>
git pull

Note: To get the <TOKEN>, click F12, go to “Application” and copy the <TOKEN>. See screenshot below.

Step 4 - Understanding the top level categories

We recommend the following top level structure for service documentation to cover the most relevant information about your application:

1. Service overview (/docs/01_service-overview.md)
   This page explains what the service does as well as relevant features. It gives an overview of the underlying architecture, states all use cases and who is the target group of this service. Information about any prerequisites (hardware, software, etc.) is clearly described.
2. Getting started (/docs/02_getting-started.md) - The “Getting started” chapter is a jump start to your service. Explain in a step-by-step way the very first steps that it takes to onboard to your service and be able to start using it. The “Getting started” chapter is a kind of Quickstart Tutorial and it allows you to introduce the fundamental concepts of your service and also prepare the user for more advanced topics at the end.
3. Basic concepts (/docs/03_basic-concepts.md) - Explain the fundamental concepts of your service to the reader. This includes entities, service specific naming conventions, general work flows and concepts, as well as interfaces to other services. Illustrations and diagrams can help to convey more complex concepts and dependencies.
4. Security (/docs/04_security.md) - Introduce the relevant security concepts that the service provides here. Please use the provided outline as orientation.
5. Release notes (/docs/05_release-notes.md) - Provide information about past service updates to your users. Sharing these insights with your user base creates transparency, customer satisfaction and reduces inquiries by the customer.
6. FAQ (/docs/06_faq.md) - List the most frequently asked questions or pitfalls experienced by users grouped by topic area. For every question provide a helpful answer to the reader. Answers can also contain a link to more relevant information.

Step 5 - Define the order of main pages

The order of your content and navigation bar elements can be defined this way:

1. The headings represent the markdown files in your repository for your service documentation.
2. The prefixes (e.g. “01_”) correspond to the order of the sidebar elements.
3. So you will find the 01_service-overview.md as sidebar element number 1 Service-Overview.
4. The template contains six possible sidebar elements with corresponding content.
5. Please note that the /docs folder should contain the markdown files of the individual sidebar elements / chapters (e.g. 01_service-overview.md, 02_getting-started.md, etc.).
6. You can create as many sidebar elements or markdown files for the individual chapters as you like.
7. However, we recommend you to focus on the most important and essential information about your service to maintain transparency.

Step 6 - Create subpages

To create subpages for the 03_basic-concepts.md (sidebar = “Basic Concepts”) proceed as follows:

1. create a folder in /docs
2. the folder name must be the same as the markdown name, but without the prefix
3. in this example your folder name is basic-concepts
4. now you can create your subpages as markdown files in this folder and prefix them to define their order on the sidebar.
5. in this example we create a subpage with the name 01_first-big-feature.md.
6. in the title of your subpage, you specify the title that should be visible on the sidebar. You can do this like in this example:

---
title: First big feature
keywords: basic concepts, features, first big feature
---

Step 7 - Customize your service documentation

Create links

You can create links as follows:

1. For main pages:

[Link name](/existing-markdown-page-name)

2. For sub pages:

[Link name](../sub-page-folder-name/existing-markdown-page-name)

3. External links:

[This is an external link to calponia](/https://www.calponia.com)

Insert images and illustrations

You can insert images and illustrations as follows:

1. For main pages:

![Image or illustration name](assets/images/your-image-name.png)

2. For sub pages:

![Image or illustration name](../assets/images/your-image-name.png)

Step 8 - Make a preview

To preview your service documentation, proceed like this:

1. Go to marketplace
2. Click on Documentation tab
3. In the section Preview you can enter the Branch name in which you have developed your documentation
4. Then click on Open preview
5. A window will open with the latest pushed version of your documentation

Step 9 - Publish the content

If you are happy with your version of the service documentation and you wish to publish it, you can do so as described below:

1. Go to marketplace
2. Click on Documentation tab
3. Set checkbox for Enable public documentation
4. When enabled, your documentation will be publicly available as soon as your application is approved for the marketplace

Step 10 - What we have prepared

We have created a template for your service documentation, which you can use. It will be available soon.