Provide a template for Readme.md

[jayoung-lee]

Readme is the most important resource to the package users. The Readme page provides first impression of the package, and the packages that don’t have thorough Readme or don’t fit users’ need get weeded out fairly quickly in the search process.

In the recent user study, users paid most attention to:

• Demo of the final output (images, gifs)
• Key features and properties
• How to use (code samples)

We can consider providing a template for the Readme.md file. Along with the template, we can also provide educational material that shows how to write good readme, along with a collection of good examples.

[sigurdm]

I transferred this to stagehand, as I believe this is where our templates live.

[kwalrath]

I'm leery of creating a full-fledged README.md file (e.g. with images) in the template, but it could have a good scaffold and point to whatever recommendations we come up with.

[mit-mit]

It would be great to align with (/propose alignment edits to) the flutter templates as part of this. They live here: https://github.com/flutter/flutter/tree/master/packages/flutter_tools/templates

[sigurdm]

I'm leery of creating a full-fledged README.md file (e.g. with images) in the template

Images in the readme are extremely helpful (as per @jayoung-lee's research) when eg. using pub to decide on a package to use - so we should consider some way of explaining how to include an image - if not in the template then where?

[kwalrath]

Images in the readme are extremely helpful (as per @jayoung-lee's research) when eg. using pub to decide on a package to use - so we should consider some way of explaining how to include an image - if not in the template then where?

Definitely would want to have an explanation and examples in an easily findable place that the README links to. dart-lang/site-www#2851 is where we're tracking the kinds of things we want to recommend.

[jayoung-lee]

If we create a template and make it available for package authors, will there be a way to track how many authors have actually accessed & used the template?

[kwalrath]

If we create a template and make it available for package authors, will there be a way to track how many authors have actually accessed & used the template?

[kwalrath]

Not the first time I've accidentally closed with comment, when I really just wanted to abandon my comment. :) But since I'm here...

I can't think of a surefire way to track it. We could put something (a footer or comment perhaps) in the markdown file that gives credit using an easy-to-search-for string or image, and have pub track the packages that have that credit.