Documentation practices

Rust documentation practices.

A lot of the best practices for Rust documentation could be found here. Most of the things on the list below are reflected in the aforementioned page.

Here’s a list of things that would be nice to have in every existing or newly introduced module:

1. Any new module that’s introduced should ideally have a doc describing what it’s purpose is, with some code examples if applicable. If said module is complex - some flow diagrams would be highly desired.
2. The public API (types, structs, static methods etc) should be documented, with code examples.
3. Domain-specific logic, especially when it’s lengthy - should either be split into smaller self-explanatory helper methods or documented within the code. The aim is to reduce the amount of context switching and the amount of time a reader needs to spend to review and wrap their head around the code.
4. Tests are often a good way to document the code and it’s usages, when done right and self-explanatory enough. In particular cases an examples folder could do the trick as well.

Readme

A readme should typically contain:

1. Installation instructions for end-user.
2. Installation instructions for developers willing to compile the project locally.
3. Running instructions for end-users:
   1. A sample command for each binary present in the repo, at least those relevant for end users.
   2. System requirements, if applicable.
   3. Caveats.
4. Contribution instructions for devs:
   1. Prerequisites if applicable: e.g. we need node.js to format md files.
   2. A list of commands that are relevant to building and testing the codebase.
5. A concise project description, what it does.
6. Some usage examples, where applicable. If there needs to be an examples folder with some sample code - there has to be.
7. Caveats, where applicable.