A recent PR (#1180) raised awareness that the first page for many new library users is its docs.rs page, generated from the crate root documentation and not the extensive Readme. While moving all of the documentation, as proposed, felt like too broad, nevertheless the following discussion was quite constructive in how the overall structure could be improved. I'll quote relevant portions on what we agreed on:

On the general structure

So in short - I didn't see any need to change the documentation, it just felt totally wasted hidden away on github where it's hard to find :)

Another advantage of the docs being on docs.rs [and within the generated documentation] rather than on github is, of course, the ability to do the intra-crate links. I know this is obvious, but I wanted to explicitly state it's really useful to see a brief code example using (for instance) GenericImage and then be able to click a link to drill down into the documentation and find out about all the detailed methods. I suspect this is the workflow most newbies would initially follow when working out how to use this crate.

Code examples and general usage:

Specifically, the code examples are the right level of complexity and I think are really helpful for newbies to the crate. (I'd definitely want to keep at least one simple and one complex example in the top-level documentation, e.g. the open and save example and the fractal example).

On section 4, the Images

The traits and structures are probably better served by linking their documentation, it's technical information and doesn't add much for judging general applicability.

I think the explanation of the roles of GenericImage/ImageBuffer/DynamicImage is good and belongs in the top level documentation too. Yes, it could be shorter, but I don't see this as urgent.

[It's] just that the code definitions is basically a duplicate of what rustdoc generates for the actual items and linking would be more apt and informative as it also allows browsing all of the related items. A short overview of their role is definitely relevant to the main documentation.

The Pixel trait

The Pixel section is plainly outdated and as well better represented if the impl section of the trait were simply linked.

• Drop the Pixel stuff

On the table of supported formats:

I think the table of formats is actually beneficial and probably belongs in the top-level documentation. I think it shows the number one feature of this library which is to support multiple image formats. (I'm not sure if you'd agree that's the number one feature but I assume it's why a lot of people want to use image).

Although it really should be the module documentation that expands on this in-depth, for example an entry all obviously depends on the format. (Not that this is directly relevant for the PR but the first column were to actually link to the modules..?)

On the fractal example

I too really like the fractal :)

➕

Actionable items

• Add top-level crate documentation with links to the most important modules and types.

• (Re-)move the definitions from the Readme, placing links to the actual documentation instead and potentially supplementing them with a more relevant high-level description.

• Condense the Image section and move specialized portions to the types. Afterall, these are currently partially undocumented and could very well get much better code examples.

• Move the fractal example up to make it more visible :)

• Drop the separate code example entirely in favor of adding showcasing the simple save/load code directly in the Supported Image Formats section.

• Link the imageops module and the imageproc crate to make it more visible.