Fix/docs layout #2034
Merged
Fix/docs layout #2034
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
didier-wenzek
force-pushed
the
fix/docs-layout
branch
from
40107df
to
4ddfcad
Compare
didier-wenzek
had a problem deploying
to
Test Pull Request
GitHub Actions
Failure
didier-wenzek
had a problem deploying
to
Test Pull Request
GitHub Actions
Failure
18 tasks
didier-wenzek
had a problem deploying
to
Test Pull Request
GitHub Actions
Failure
didier-wenzek
force-pushed
the
fix/docs-layout
branch
from
5676f0f
to
9175a44
Compare
didier-wenzek
had a problem deploying
to
Test Pull Request
GitHub Actions
Failure
reubenmiller
approved these changes
Jun 20, 2023
albinsuresh
reviewed
Jun 21, 2023
There was a problem hiding this comment.
Quite happy top level restructuring. I just have a few comments/queries on some of the content. I also noticed a few docs missing, a few under the wrong sections etc. All that need not be fixed in this PR itself, as that was not the main goal. Just pointed them out so that there's clear list of items to fix even in a follow-up PR.
| - [Supported Operations Management for Cumulocity IoT](./tutorials/supported_operations.md) | ||
| - [Write my software management plugin](./tutorials/write-my-software-management-plugin.md) | ||
| - [Build Thin Edge for a Yocto Linux distribution](tutorials/yocto-linux.md) | ||
| - [Operate devices](operate/index.md) |
There was a problem hiding this comment.
Suggested change
| - [Operate devices](operate/index.md) | |
| - [Operate thin-edge](operate/index.md) |
[Minor] Just so that it goes along well with the other sections as in:
- Operate/Use thin-edge
- Extend thin-edge
- Contribute to thin-edge
There was a problem hiding this comment.
This was my first proposal, but I changed my mind because the goal of the user is truly to operate his devices not thin-edge.
docs/src/SUMMARY.md
Outdated
| - [How to add self-signed certificate root to trusted certificates list?](operate/security/010_add_self_signed_trusted.md) | ||
| - [How to set up client/server authentication for the local MQTT broker](operate/security/029_mqtt_local_broker_authentication.md) | ||
| - [Connection](operate/connection/index.md) | ||
| - [How to connect /index cloud end-point?](operate/connection/004_connect.md) |
There was a problem hiding this comment.
Suggested change
| - [How to connect /index cloud end-point?](operate/connection/004_connect.md) | |
| - [How to connect /index cloud end-point?](start/connect-c8y.md) |
I feel we can remove these kinds of redundant documents describing exactly what the "Connect my device to Cumulocity IoT" doc describes in the Getting-Started section. May be it's better to have this entry point to the same getting-started doc as I see no benefit in keeping it different.
BTW what did you mean by "index" here?
There was a problem hiding this comment.
BTW what did you mean by "index" here?
A typo! Using vim commands on a non-vim editor!
I feel we can remove these kinds of redundant documents describing exactly what the "Connect my device to Cumulocity IoT" doc describes in the Getting-Started section. May be it's better to have this entry point to the same getting-started doc as I see no benefit in keeping it different.
We definitely need to address all these redundancies - but independently.
docs/src/SUMMARY.md
Outdated
| - [Connection](operate/connection/index.md) | ||
| - [How to connect /index cloud end-point?](operate/connection/004_connect.md) | ||
| - [Processing Telemetry Data](operate/telemetry/index.md) | ||
| - [How to use `tedge mqtt` module?](operate/telemetry/005_pub_sub.md) |
There was a problem hiding this comment.
Suggested change
| - [How to use `tedge mqtt` module?](operate/telemetry/005_pub_sub.md) | |
| - [How to send measurements](start/send-thin-edge-data.md) |
That 005_pub_sub.md file is more of a documentation of the tedge mqtt cli tool, just using measurements as an example. It might be better to just point to the same doc used in the getting started section, again to avoid redundant content.
But then I'm wondering where to keep the documentation of this tedge mqtt tool. Another dedicated section for "TEdge CLI"? Since the reference docs for these tools already exist, I don't really see the need for one more dedicated section like that for all those subcommands. May be just a single document in the Getting Started section introducing all the tedge cli commands with links to the references doc for more details.
There was a problem hiding this comment.
This 005_pub_sub.md page highlights the issues we have with the current documentation: this is a series of loosely related facts with no clear message being conveyed.
But then I'm wondering where to keep the documentation of this
tedge mqtttool.
I would simply use tedge mqtt along the docs - stressing some key points only when appropriate (e.g. a note telling that an alarm is sent as a retained message), and pointing the user to the reference guide.
One can have a more general howto "interact with thin-edge using MQTT" that tells why, when and how to use tedge mqtt and mosquitto.
May be just a single document in the Getting Started section introducing all the tedge cli commands with links to the references doc for more details.
This is good idea to add a "getting started" guide that gives an overview of the tedge command.
| @@ -59,7 +59,7 @@ For Apama projects: | |||
| 1. The version must be suffixed with `::apama` as in `1.0::apama` or just `::apama` if no version number is necessary. | |||
| 2. The uploaded binary must be a `zip` file that contains the `project` directory. If a directory named `project` is not found by the plugin at the root level in the zip, it is considered invalid. | |||
|
|
|||
|  | |||
|  | |||
There was a problem hiding this comment.
The images dir could be moved to the top level in a follow-up PR, so that we can get rid of the how-to-guides dir completely.
docs/src/operate/installation/015_installation_without_deb_support.md
Outdated
Show resolved
Hide resolved
docs/src/operate/installation/015_installation_without_deb_support.md
Outdated
Show resolved
Hide resolved
docs/src/operate/installation/015_installation_without_deb_support.md
Outdated
Show resolved
Hide resolved
| <p align="center"> | ||
| <img src="./images/manual_installation-download_source_code.png" alt="Sublime's custom image"/> | ||
| </p> | ||
|  |
There was a problem hiding this comment.
[Unrelated, just curious] Sublime?
There was a problem hiding this comment.
I guess the name of the tool used by the primary author.
Yep, there is still a lot to do. What I would like reach quickly is a state where these improvements can be done independently. |
didier-wenzek
had a problem deploying
to
Test Pull Request
GitHub Actions
Failure
albinsuresh
approved these changes
Jun 21, 2023
The plan is to re-structure the documentation around usage levels (taste / understand / use / extend / contribute) rather than documentation types (tutorial / howto / concept / reference). These documentation types are still used but more or less depending the usage levels. This first commit only updates the overview along this new structure - no content is moved, added or updated. Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>
Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>
Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>
Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>
These have been replaced by section more adapted to the role of the readers and their experience with thin-edge: - Getting started - Concepts - Operate - Extend - Contribute - Reference Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>
This will be helpful for Docusaurus to set approprite title and tags. Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>
Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>
didier-wenzek
force-pushed
the
fix/docs-layout
branch
from
e63a7bf
to
af33dd7
Compare
didier-wenzek
temporarily deployed
to
Test Pull Request
GitHub Actions
Inactive
Robot Results
Passed Tests
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Proposed changes
The documentation is re-structured along the role of the readers and their experience with thin-edge
(start / understand / use / extend / contribute) rather than documentation types (tutorial / howto / concept / reference).
Using thin-edge on a device (i.e. operating the device) is structured along the main features of thin-edge
(install / config / security / connection / monitoring / operations / managing / troubleshooting).
These sub-sections will have to be refined while the documentation improved.
Types of changes
Paste Link to the issue
#1238
Checklist
cargo fmtas mentioned in CODING_GUIDELINEScargo clippyas mentioned in CODING_GUIDELINESFurther comments