Where should we maintain comprehensive documentation?

[tomhoule]

Many projects in the rust community maintain guide-level documentation with gitbook and keep the top-level crate docs and the README minimal. So far every new feature has gone into the README but this is not scalable.

There are also projects like structopt that maintain their guide documentation at the root of the rustdoc docs.

Does someone have some experience or advice on this front?

[peterfication]

I would be happy to support with porting the current documentation to Gitbook. I haven't worked with Gitbook so far and it would be a good chance to get to know it. It is used by Juniper as well, so it could be a sub project there.

I started playing around with it already a little bit: https://peterfication.gitbook.io/graphql-client/

[tomhoule]

Hi Peter :) Thanks! We can just port the current README for now. Ultimately we are going to want to reduce the README to the most important info (what the library does, what the API looks like and how to use it), and find a different structure for the book. I think a 2-parts structure would be cool: first a guide-like explanation, then detailed topics (custom scalars, error handling, etc.).

As for the hosting there is a discussion in the graphql-rust organization and the current plan is to have a landing page on graphql.rs and separate subdomains for the docs of different crates (so graphql-client docs will be separate from the juniper ones).