Many crate pages are useless dead-ends

[sp3d]

This is something of a workflow critique rather than a traditional bug report, but nonetheless I hope to keep things relatively uncontentious. Bearing that in mind:

My primary usage of crates.io is to find libraries which might be useful dependencies for projects I start. My workflow for this is relatively simple: perform a search or few for terms that seem relevant to the problem at hand (e.g. "irc" or "color") and then try to evaluate the crates listed to see if they're relevant to my problem and compatible with the approach I'd like to take.

However, a lot of pages displayed for crates are "dead ends" in this goal.
Two examples are http://crates.io/crates/rchat and http://crates.io/crates/color:

First, the page lists the name of the crate, which is obviously the right thing to do so the user knows which crate they're interacting with.

The next piece of information to which the eye is drawn is a bit of code:

Cargo.toml color = "0.0.1"

For a user familiar with cargo, this is identifiable as the line to add to a Cargo.toml, though as issue #126 mentions it doesn't explain precisely how to do it, which would probably benefit new users more.

However, this information isn't useful to a user at this stage of their interaction with the page. They don't yet know if they want the crate in their project, because they don't know what it really is or does!

On the right, a user can see (and potentially e-mail) authors, which might be helpful in evaluating quality of a crate if they're familiar with some of the authors from the greater community. But quality isn't relevant either until one knows what exactly the crate does.

For this, a user would first reach for the "About This Package" description (except these crates have none), but even this is often only enough to know the vague topic of the crate rather than getting into details of whether its interface meshes well with the design of a user's project.

To truly evaluate a crate to see if it's suitable, one needs to read either API documentation or source code. API docs don't always exist, but source code does. Yet crates.io provides no link to the source code archive! Even more frustratingly for the eager user, the bottom half of the page is full of statistics on downloads over time, which painstakingly documents how many other people have accomplished the goal they've now adopted: to download the crate and dump it on the floor to see if they can make use of the goodies inside. But search as you might, there's no way to download these crates from their crates.io page!

It is true that crate authors can improve this situation vastly for their own crates; they can set a description for the "About This Package" field which is displayed above (but not more prominently than) the Cargo.toml line. They can also add repository and API documentation links. Some crates do all these things and it's very nice; until I asked about this workflow problem in IRC, I had assumed crates which had no links or descriptions at all were bugs in crates.io or old rows grandfathered into a database schema change.

Regardless, I think we should give users the best possible experience rather than leaving them at the mercy of crate authors, making crates.io as useful as it can be with the crates it has rather than hoping for sea change in crates themselves. I think it's certainly wrong to have crate pages on which there are no productive links a user can click.

My concrete suggestions are to:

• replace blank descriptions (which are invisible) with a call-to-action for the crate author to provide a crate description
• prominently link to the source code archive for a crate on its crate page
• emphasize crate description in crate pages more than the Cargo.toml line

[carols10cents]

I think this is on crate authors rather than crates.io, and I think the situation has been improved considerably by rendering READMEs on crates.io.