[Bug]: Documentation Improvements

[alexkingnz]

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

Current Behaviour

The documentation could be improved. I tried to use this crate but ended up using the cbor crate instead, and wasted a few hours including this question: https://stackoverflow.com/questions/78654733/what-serde-format-should-i-use-to-serialize-a-hashmap-keyed-by-u832 until drewtato hinted I was using the wrong crate.

How I got here:

• serde_json wasn't meeting my needs
• I looked for a serialization format at https://serde.rs/, which links CBOR to here.
• I read "You're probably looking for from_reader() and into_writer(), which are the main functions," and immediately wanted to look at the API docs. Those weren't linked anywhere, so...
• I googled CBOR rust, and took the top hit which was https://docs.rs/cbor/latest/cbor/...

Granted I made a mistake there. However the documentation could have made it easier for me...

Expected Behaviour

I suggest at least "You're probably looking for from_reader() and into_writer()" could be links to the correct docs at docs.rs. (I see they are on the page at docs.rs itself, but not on the github page.)

Also, consider putting instructions like "Add the crate "ciborium" to your Cargo.toml, e.g. with cargo add ciborium" at the top of the docs? This is good for beginners and also helpful in general.

Finally a mention (especially since this crate is linked with a "CBOR" hyperlink at https://serde.rs/) that the cbor crate is not related to this one, and was an earlier non-serde effort, might be appropriate.

Let me know if you'd like a pull request for that?

Environment Information

Linux replace 6.1.0-21-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) x86_64 GNU/Linux
-bash: enarx: command not found
-bash: enarx: command not found

(Just for kicks and since this field is apparently required)

Steps To Reproduce

No response

[rjzak]

Thanks for the feedback! Documentation is important and is always something which could use improvements.