grammers
grammers copied to clipboard
Lonami
Extensive, beginner friendly documentation
Any product will be useless unless people know how to use it. Once we settle on a stable design, we should document every public module of (at least) the client library with instructions on how to get started, where to look, a section on using raw API and understanding the return types…
I think we should refer to such documentations as a Cookbook or a Guide as in general how most other platforms do. And not dilute the documentations too much.
It would certainly add a burden of maintaining such a Guide but I think keeping it separate from Documentations would cause a lot less pain and confusion to beginners, while allowing others to use Documentation without being annoyed by obnoxious amounts of explanation.
It is definitely plausible to host a separate guide under https://gramme.rs, or even use this project's wiki (which we can link as a guide from the main site or the documentation). So doing it like this instead of cluttering the reference (in https://docs.rs) is definitely a fair enough idea.
In general starting with a simple Bot example would be good and also help with reaching to a MVP stage for the project.
Making general examples would also help us identify what needs to have better abstractions for implementation, like Client API is one which can obviously use a lot of work. Such examples would help identify the most important things to work on to make this project actually usable.
There are already some under grammers-client/examples. For the rest of libraries, examples within the documentation comments are probably enough, because they provide small building blocks. On contrary, the client is about integrating those to build something bigger, so separate example files make the most sense.
Good posts to keep in mind:
- docs.rs now allows you to choose your build targets
- Guide on how to write documentation for a Rust crate