Documentation improvements #58
Description
Find in PR #57 some typo fixes, additionally, I would like to bring up some other parts of the documentation that, from a newcomer point of view, could use some love.
-
At: https://zenoh.io/docs/getting-started/quick-test/
The section "Managing the admin space" has all the code boxes about 1/3 smaller than the rest (and the commands are barely visible). I guess it's not really a typo, but it's probably an easy fix. Note: I tried to fix it but... the markdown file looks exactly like any other part that is correctly rendered. -
At: https://zenoh.io/docs/getting-started/first-app/ at the very end in "Other examples"
It links to the C examples, but these don't have a README like the Python or Rust ones. -
At: https://zenoh.io/docs/getting-started/troubleshooting/ "Known troubles with the APIs" [1]
I would request to add at some point in the future a tutorial on how to sync the time in between machines (at least for linux). -
At: https://zenoh.io/docs/manual/configuration/
Not really a typo, but there is a lot of talk about stuff before version 0.6, which for me as a newcomer is a bit noisy. Maybe add a section "If you come from version 0.6 or earlier" and keep the entry cleaner. -
At: https://zenoh.io/docs/manual/configuration/#adminspace-configuration
Note that while you may attempt to change any part of the configuration through this mean, not all of its properties are actually watched.
For example, while the storage plugin watches for any change in its configuration and will attempt to act on it, the REST plugin will only log a warning that it observed a change, but won’t apply it.
Changes to non-plugin parts of the configuration may be registered by the configuration, but not acted upon, such as the mode field of the configuration which is only ever read at startup.
Not really a typo, but I found this explanation pretty confusing. Maybe a list or diagram of "Watched properties and how they are acted upon changes" would help.
TODO: this part hasn’t been redocumented yet. Feel free to contact us on Discord to get more information.
Well, it's a TODO, just thought I'd bring it up.
[1] Off-topic: In https://zenoh.io/docs/getting-started/troubleshooting/ it says that: "Error treating timestamp for received Data" may appear if there is a discrepancy in between clocks of 100ms. When teaching ROS to students, specially in environments without access to the internet, just a local network, drifts in the clock were a relatively common issue. By using messages without a timestamp, we could overcome teaching the basics ignoring these kind of problems. Is there a way to ignore timestamps in zenoh? Or tune the discrepancy?