Recommend best practices for package README.md files

[kwalrath]

Related: dart-archive/stagehand#683

Package READMEs often serve triple duty, as API homepages, pub.dev homepages, and repo homepages. For example, consider, the README for the shelf package (https://github.com/dart-lang/shelf/blob/master/README.md), which is rendered in the following places:

• https://pub.dev/packages/shelf (package homepage; other tabs include Example and Installing)
• https://pub.dev/documentation/shelf/latest/ (API doc homepage)
• https://github.com/dart-lang/shelf (repo homepage)

If you have examples of good READMEs (preferably with examples of WHY they're good, and HOW they could be even better) and issues related to READMEs, please comment on this issue.

https://github.com/thegooddocsproject/templates might be interested in what we come up with.

/cc @jayoung-lee

[kwalrath]

Maybe we can collect guidance in this comment. Here's a start.

Dart-specific guidance for READMEs:

• If the package has associated UI, include a screenshot.
• Use absolute URLs for links, images, etc., so that they'll work no matter where the README is published.

General guidance for READMEs (not Dart-specific):

• The README checklist from @ddbeck: https://github.com/ddbeck/readme-checklist

[filiph]

Additional guidance (totally optional):

• spend some time on the short description at the top of the README. It should concisely describe what the package is about, at a glance.
• screenshot is better than not, mov/gif is better than static image
• screenshot above the line (visible close to the beginning of the README
• use badges (CI/CD, coverage, etc.) to signal maintenance, stability
• use code formatting (```dart, three backticks+dart)

  final like = "this";

  instead of

  final like = "this";
  

• A short and sweet code sample in README is nice. Put a more complete example in example/example.dart. The one in README doesn't need to compile: it's there to explain.

We might consider writing a short article on pub.dev/ about this? Because then we can link to it from the README, and we can add visual aids:

Some resources:

• https://github.com/matiassingers/awesome-readme
• https://blog.bitsrc.io/how-to-write-beautiful-and-meaningful-readme-md-for-your-next-project-897045e3f991
• https://www.makeareadme.com/
• https://bulldogjob.com/news/449-how-to-write-a-good-readme-for-your-github-project
• https://medium.com/@meakaakka/a-beginners-guide-to-writing-a-kickass-readme-7ac01da88ab3
• https://gist.github.com/PurpleBooth/109311bb0361f32d87a2 (this is too generic and most of the sections are not applicable, but I think we could get inspired by some of the parts there)
• https://dbader.org/blog/write-a-great-readme-for-your-github-project (source of the image above)

[jayoung-lee]

I'd also suggest authors to:

• start README with a short sentence that summarizes what the package can do
• include a "Features" section that lists key features (preferably with bullet points)
• include a "Parameters" section that lists available parameters, if applicable (preferably in tables)
• include a "Getting started" or "How to use" section, which helps users quickly understand how to use the package
• include at least one short code sample that users can quickly copy and paste to test how the package works

+1 to writing a short article on pub.dev! The article may include recent UX research insights on how Flutter/Dart users search for packages on pub.dev and consume README files there. I'd also like to add tips like:

• make sure to add LICENSE information
• make sure that the description in the pubspec.yaml file is up-to-date

[kwalrath]

@jayoung-lee said:

• include a "Parameters" section that lists available parameters, if applicable (preferably in tables)

This sounds more detailed than I'm used to seeing in a README. Can you point me to an example of this? (Maybe the package API tends to reuse the same parameters in multiple places?)

[jayoung-lee]

Then it's probably because some packages visited during the recent user study were simpler than others?

Participants visited few pages that listed parameters, attributes, or properties, and they found it useful when deciding whether to test the package or not.

• https://pub.dev/packages/markdown_editable_textinput
• https://pub.dev/packages/qr_flutter
• https://pub.dev/packages/bluetooth
• https://pub.dev/packages/intro_slider

[kwalrath]

I took a quick look at those package pages plus the other places where their README.md is used. There are some issues with sharing the content, although not as many as I expected. Mostly the issues are with dartdoc rendering differently or not finding images because they had relative URLs. Interestingly, relative images worked on pub.dev/packages pages.

• markdown_editable_textinput
  • https://pub.dev/packages/markdown_editable_textinput
  • https://pub.dev/documentation/markdown_editable_textinput/latest/
    • Checkboxes (in Features section) don't render well
    • Demo section appears empty (no image, no broken image; the path is relative, and I wonder if dartdoc supports gifs)
  • https://github.com/playmoweb/markdown-editable-textinput
• qr_flutter
  • https://pub.dev/packages/qr_flutter
    • Refers to AUTHORS and LICENSE files (no link, no visible way to find the AUTHORS file)
  • https://pub.dev/documentation/qr_flutter/latest/
    • Refers to AUTHORS and LICENSE files (no link, no help for finding these files)
  • https://github.com/theyakka/qr.flutter
• bluetooth
  • https://pub.dev/packages/bluetooth
  • https://pub.dev/documentation/bluetooth/latest/
    • checkmarks don't render as images; instead, they render as :white_check_mark:
  • https://github.com/truongsinh/flutter_bluetooth
• intro_slider
  • https://pub.dev/packages/intro_slider
  • https://pub.dev/documentation/intro_slider/latest/
    • All images are broken (seem to be relative).
  • https://github.com/duytq94/flutter-intro-slider

[kwalrath]

To be clear... I believe that of the 3 README usages, the package page is most important. It's good that if the README works in the repo, it seems highly likely to work as a package page. I'm curious how many people look at the API docs on pub.dev.

[jayoung-lee]

I agree that the package page is most important!

It seems like very small number of pub.dev visitors (~5% of pageviews) open API docs (/documentation/**), compared to 72% of pageviews being to /packages/**.

[kwalrath]

It seems like very small number of pub.dev visitors (~5% of pageviews) open API docs (/documentation/**), compared to 72% of pageviews being to /packages/**.

That's very good information to have! It's especially telling since there's only one URL for each package under /packages/, but multiple URLs under each package's /documentation/ path (even if you only consider /documentation/latest).

[parlough]

We now have a great article covering this with #3147 which can be found at https://dart.dev/guides/libraries/writing-package-pages.

Thanks for the amazing work on this article, it's a great resource!

Closing this for now. If there are any other additions you'd like to see, we can discuss them in a targeted, follow-up issue.