Improve thin-edge.io documentation structure

[andrej-schreiner]

As a user of thin-edge.io I want to have a better structured documentation :

• I am confused between How to and Tutorials - here I need a clear path on how to get started with thin edge and a structured walk-through on how to set up and use all features
• as an embedded engineer I am currently lost where to find which information (only the search can help) so I need an overview and better structure on how to extend thin edge
• Additional points: We need to add links to tutorials to find further info, we need to have a single point of truth for our doc structure and clean-up the links

Outcome: We need to have a clear proposal of what we want to change in the current doc, review this with stakeholders and move to delivery.

[hansb001]

• Requirements/prereq guide

• Detailed installation guide

• Detailed configuration guide

• Detailed developer guide, how to extend.

• Contribution guide

• Getting started guide, like hello world

• How to guides and tutorials need to be combined, no difference

• Website gif (installation) has to be updated

• Less text, more images

[didier-wenzek]

Sure the documentation has to be improved but I disagree on many points.

How to guides and tutorials need to be combined, no difference

Making a difference between tutorials and howtos is a key. Howtos give the details once you know what to do. Tutorials give an overview of the things that can be done and how they relate.

• See the documentation system also known as the Diátaxis.
• What difference between a detailled guide and a tutorial? between a detailled guide and a reference guide.
• The issue I see with the current howtos is that they have been written with a 1-1 relationship with the code changes. There are 4 howtos about installations and they are listed by date of creation. Having a single one or grouping them would help.
• The tutorials have all been written for the same user: the device owner. Nothing or too few for a developer who want to extend thin-edge and implement an agent with thin-edge. The issue here is far beyond the doc: all the features have been designed and implemented for the device owner and not for an agent developer. This has badly impacted the documentation but also the features (somehow this is why we have so many features where you need to ssh the device). We need to address the root cause here and have a better understanding of who is the user.

Less text, more images

More images might help. Less text definitely not. The text needs a better organization, not to be removed. More code samples might help.

[didier-wenzek]

Tickets and discussions regarding documentation:

• Documentation improvement ideas
• Simplify the process to write specifications and user documentation
• Document programmatic example for sending telemetry data from thin-edge
• Document commonly seen issues with remote operation handling with resolutions
• Document commonly seen Cumulocity connectivity issues with resolution
• Improvement of section "How to connect external devices" regarding needed parameters
• Improve user experience for first-time thin-edge.io users

[switschel]

I think what is needed are clear types of documentation like Quick Start Guides, Concepts/References/Informations, Tutorials & How to Guides. We should have more top level categories like Quick Start, Installation, Configuration, Development, Build, Extensions etc. and on all categories you have all kind of concepts, tutorials & How To documentation.

Especially for concepts we need more graphical content.

That would make it much easier to find the relevant content. I will come up with a proposal.

[switschel]

Not sure where to document so I do it here. My proposed documentation structure:

1. We need a comprehensive Getting Started Guide : https://thin-edge.io/#!get-started is not enough and the How-Tos and Tutorials are too unstructured. The Getting Started Guide should contain concepts and sub chapters like:
   1.1 Installation --> Concepts of thin-edge.io and how to install it on a reference platform
   1.2 Configuration --> Describe necessary configuration steps, refer to complex configuration in docu
   1.3 Run --> Run it on a reference device
   1.4 Develop & Build --> Describe how to contribute and make custom builds
   1.5 Extend --> Describe how thin-edge.io can be extend

The main goal should be to have a full walkthrough from first touch point to having an (extended) example running on a device. Here we can reuse or refer exiting How-To and Tutorial Guides. Especially the concept part must be enhanced as the current guides are too hands-on less concept-wise.
It should be the first touchpoint document for all who have no experience with the thin-edge at all but want to try it out.

2. We can keep the tutorials and how-to but should add categories to make clear what is in focus of the how-to guides. How to send MQTT messages should not be mixed with How to install thin-edge. First "Transport" Second "Installation" Category.

3. We should add a new block concepts where we explain the concept of the thin-edge.io which we can re-use and refer in the quick start guide. Make sure the concepts are well and graphically explained. Examples of to be documented concepts: "thin-edge data model, thin-edge runtime, thin-edge cloud transport, thin-edge mapper etc."

As a reference have a look here :https://docs.microsoft.com/en-us/azure/iot-edge/?view=iotedge-2020-11 (left navigation tree).

4. Once we have a clear concept how we package, run & monitor all components of the thin-edge.io we need a clear & full API documentation which includes all topics/endpoints/interfaces and messages which can be used to perform the previous mentioned task. Example: MQTT thin-edge API describing all pre-build topics and reserved cloud connector topics etc. The API documentation should be referred in the How-Tos, Tutorials & Getting Started Guide

[didier-wenzek]

• It's a good point to have a "getting started guide" that address all the main aspects of thin-edge including how to extend it (and goes beyond what was available version 0.1!).
• Indeed I prefer the category proposed by @switschel : Install/Configure/Run/Develop/Extend rather than what we have today with user vs developer documentation (that makes little sense when the users are developers). I have a question though. What difference do you make between Develop and Extend ? You mean using thin-edge to develop an agent vs updating the rust code base of thin-edge?
• About the proposal for a new block about concepts, I would like to stress that we have one - that for some mysterious reasons has been hidden and unmaintained : architectur.
• For the API, I can only agree. Currently the API, MQTT topics and message payload is scattered all over the howtos. We need a clear and comprehensive API documentation.

[switschel]

Difference between Develop vs Extend like you assumed:
Develop/Contribute to thin-edge (core) project.
Extend => Use APIs to develop Plugins, unofficial Extensions (not part of the thin-edge.io core project).

[hansb001]

Most important outcomes of discussion om 30/8:

• agree on getting started tutorial as proposed by Stefan
• agree on well-written concepts of thin-edge.io are missing. Concepts guide must be extended with (schematic)images, see for an example cumulocity concepts guide.
• Not sure who will be the owner of the documentation, maintenance can be a lot of work.
• Tutorial: begin to end (to test)
• How To: testcase
• Hans to create new md-page ( private) to set up new structure and fill with existing text. Next meeting discussion about this, and refine. Is set up here: https://github.com/thin-edge/doc-structure
• Stefan adds to the new structure
• Didier informs team about work for new documentation structure.
• when structure is definitive, whole team should work on documentation
• issue with available time to work on new documentation

[didier-wenzek]

Hans to create new md-page ( private) to set up new structure and fill with existing text. Next meeting discussion about this, and refine. Is set up here: https://github.com/thin-edge/doc-structure

• Why a private work-in-progress? It's really important that any can have a say.
• Why a new repository? Having another repository for the documentation makes sense only if another team is responsible of it - which is not the case for now.

[hansb001]

Some input from our Priorities meeting:

• Focus on How To, therefore we can have a look at previous meet-up topics like (node-red, codesys, python, analytics etc.
• Hans and Stefan work closely together on structure
• Next meeting, outcome should be set of tasks

[hansb001]

• create feature branch and later on merge to new main branch
• merge in agile approach

[switschel]

@didier-wenzek What is your proposal? How should set up the new documentation without interfering the old one? should we create a new branch? PR?

[didier-wenzek]

@didier-wenzek What is your proposal? How should set up the new documentation without interfering the old one? should we create a new branch? PR?

It's important to have this doc refactoring happening in the same repository as the code, so the team can update the content in parallel. Look for instance this PR that updates the documentation accordingly to a fix.

So we need to improve the documentation using regular PRs (on branches from a writer fork of the main repository).

I would also avoid to have a single huge PR. Things like merging all the install Howto in a single one could be a PR. Adding a getting started guide would be another.

[switschel]

Ok, I think we did it right so far. I forked the thin-edge repo and made make changes to my forked repo in a new folder called "new_docs" so we don't interfere with the existing documentation.

This structure (md) can be merged to thin-edge so you can review it and start adding content in the same folder. Later on we can replace "docs" with "new_docs".

[hansb001]

Also add all relevant MQTT topics to the documentation (reference)