This issue tracks improvements to our documentation. See our roadmap for the high-level vision that the tasks tracked here fit into.

Top-level docs

Framing

• Documentation frames zerocopy as a general-purpose tool for replacing unsafe code, not just as a tool for parsing or another specific task. Done in #386.
• Consider adding examples of domains in which zerocopy is used in order to convey the breadth of use cases and suggest that it's not primarily meant for any single use case

Use cases

• Top-level documentation points users in the right direction for most common use cases
  • This documentation must not assume a familiarity with unsafe code, but should instead focus on use cases

Correctness and soundness

• Documentation frames the "unsafe as the cryptography of the Rust world" idea
• Documentation describes zerocopy's future-soundness guarantee
• Documentation describes the steps we take to ensure soundness
  • Safety/soundness arguments, especially with regards to reasoning only in terms of documented guarantees by the language reference or the standard library documentation
  • All tests run under Miri, including under experimental memory models (currently: stacked borrows, tree borrows, and strict provenance)
  • Once we use them, mention formal modeling tools (#378)
• Consider citing high-profile users who are comfortable with this

Module/item docs

• Items (types, methods, etc) provide toy examples to demonstrate basic usage
• Modules and items whose usage is not self-evident provide more involved examples that help to teach users the correct mental model
• Modules and items call out common use cases that would be reasonable to solve using them
• Modules and items call out common use cases that would not be reasonable to solve using them, but which it would be easy to mistakenly believe would be reasonable to solve using them (e.g., FromBytes for parsing without considering endiannness)

Miscellaneous

• Fully-fledged implementation examples in a separate module or in the examples directory

@kupiakos has provided this writeup and offered that we can incorporate it into our docs; it includes a lot of good examples and explanations