search

dart-lang / pub-dev

The pub.dev website
https://pub.dev
BSD 3-Clause "New" or "Revised" License
771 stars 141 forks source link

Example tab is not beginner friendly #2305

Open vincevargadev opened 5 years ago

vincevargadev commented 5 years ago

I find the example code very useful in the Dart ecosystem. I know that for most plugins,

If a new user is checking Dart Pub's Example tab, the rendered HTML for most packages is pretty useless in finding the actual code examples.

The user needs to know that there's a "Repository (GitHub)" link on the side and that the example can be looked up in the repository's example folder (in simple cases where one repo => one package).

In my opinion, this user interface should be improved. One quick-win solution could be just a link to the repo's example folder (of course, I don't mind finding an even better solution)

Example packages with "almost useless" example tabs on Pub

These are all very popular packages and every package has examples. As a new user, however, just by checking the pub.dev website, I cannot really tell that there are actually good examples for these packages. I cannot click on anything, no links to the actual source code.

jonasfj commented 5 years ago

I'm not exactly sure how, but I agree we should offer a code browser for all the files in the example folder, or something like that.

vincevargadev commented 5 years ago

Thanks for the quick feedback. Yes, that would be awesome. Though a complete "code browser within Dart Pub's Example tab" solution sounds like a major undertaking.

Just an idea: Maybe as a first iteration, place a link to the repository's example folder after the rendered README.md (I'm not 100% it's that simple, but sounds easier than the code browser). I don't know how it would work for repository's with multiple packages (e.g. flutter/plugins) and repositories that are not on GitHub (GitLab, BitBucket, whatever)

For example, in uni_links package's case, we could link to https://github.com/avioli/uni_links/tree/master/example

jonasfj commented 5 years ago

Yeah, the problem is repositories with multiple packages...

It might be easier to file PRs for these packages to add absolute links in the example/README.md file instead...

If we just fix the top 10 packages that'll go far :)

isoos commented 5 years ago

It might be easier to file PRs for these packages to add absolute links in the example/README.md file instead...

We have #2018 for fixing relative links in the example/readme.md. It is not that hard but we haven't had the priority for it yet.

isoos commented 5 years ago

We could also link to the example folder on GitHub... E.g. the first line (example/README.md) could link to the folder.