thin-edge
Create overview concept documentation
-
Document writers should try to strive for easy to understand prose accompanied with graphical content that illustrates their points.
-
At the forefront should be the readability of targeted users (persona's) and not the developers of thin-edge.io themselves.
-
Graphical content can be SVG diagrams or ASCII art and be really helpful. But avoid JPG or PNG images as much as possible. The content of such images is not searchable and GUI screenshots are difficult to maintain. Also, make use of code blocks where appropriate.
-
Use links to refer to related content.
-
Concept guides clarify and illuminate a particular topic and is understanding-oriented.
-
Concept Guides are most useful for readers who want to build a deeper understanding of a particular topic.
-
here is a list of questions to consider for writing:
-
What is the central, underlying concept for this topic? Why is that something worth learning about? -
What historical background or past decisions would be helpful for newcomers trying to understand this concept? -
Are there any other solutions or approaches? What are the pros and cons of each approach? -
What other viewpoints should be considered?
Rather than focusing on specific technical details, Concept Guides take a step back to look at the broader picture. Concept topics explain abstract ideas and introduce terminology.
Concept topics tend to be relatively unaffected by feature enhancements over time. While additions might be needed to support new options and their use cases, they tend to require less rewriting than task topics.
At a minimum, a concept topic includes the following components.
-
A title -
One or more body paragraphs.
It can also include the following additional structured information.
-
One or more examples. -
Two or more subsections, marked by subheadings. -
A list of related topics.
Hi @hansb001 ,
Your points are good and valid I guess but actually matching all concepts guide. This issue is for the concepts overview part of the documentation so my suggestion would be to structure the issue like follows:
Content
Generic concepts about thin-edge. In which scenarios thin-edge can be used. Thick Edge vs Thin edge, Graphical thin-edge architecture with all components. On a high level explain the main components of the thin-edge.
This is the abstract of other concepts
Target Persona
User role: Solution Architects, Developer, Potential Partners Level of thin-edge knowledge: Beginner
References
Add references to the component concept details.
Acceptance Criteria
see some of your points.
About the guidelines provided here. I agree with @switschel , these are good but too generic.
About the target user. These need to be aligned with the vision document (WIP).
About the level of knowledge. I have a mix feeling. Why a concept guide should target a beginner. This is definitely the case for a tutorial. But a concept guide should be interesting whatever your level of expertise. I thing such a guide is more useful when you want to master a topic you already played with.
If you are an expert in thin-edge you don't need to read the concept overview about thin-edge I guess because you already have that knowledge. For other concepts the level of knowledge might be different.
Content
Generic concepts about thin-edge. In which scenarios thin-edge can be used. Thick Edge vs Thin edge, Graphical thin-edge architecture with all components. On a high level explain the main components of the thin-edge.
This is the abstract of other concepts
Target Persona
User role: Solution Architects, Developer, Potential Partners, embedded software engineer Level of thin-edge knowledge: Beginner
References
Add references to the component concept details.
Acceptance Criteria
Document writers should try to strive for easy to understand prose accompanied with graphical content that illustrates their points.
At the forefront should be the readability of targeted users (persona's) and not the developers of thin-edge.io themselves.
Graphical content can be SVG diagrams or ASCII art and be really helpful. But avoid JPG or PNG images as much as possible. The content of such images is not searchable and GUI screenshots are difficult to maintain. Also, make use of code blocks where appropriate.
Use links to refer to related content.
At a minimum, a concept topic includes the following components.
A title One or more body paragraphs.
Thick Edge vs Thin edge
- Thick Edge is not a thing, just a nickname for "Cumulocity IoT Edge".
- The documentation about thin-edge should not even say a word about "Cumulocity IoT Edge". This must be the reverse, the Cumulocity documentation pointing to thin-edge documentation and maybe clarifying Cumulocity IoT Edge vs thin-edge vs thin-edge Commercial Edition.
@didier-wenzek I could live with that but at least edge computing must be roughly explained and be part of the overview.
From my side everything is provided! Is there anything missing so this issue can be worked on?
From my side everything is provided! Is there anything missing so this issue can be worked on?
It depends on who will work on it ;-).
I would prefer to have one of you, @hansb001 or @switschel, write this overview, and doing so, provide a concrete example of the writing style and the content you expect. I'm afraid that otherwise the work will have to be done again and again. The current documentation has been written by the developers of thin-edge with a genuine intention to help the users of thin-edge (and in no case only themselves). But good intentions are not enough.