search

dart-archive / stagehand

Dart project generator - web apps, console apps, servers, and more.
https://pub.dev/packages/stagehand
BSD 3-Clause "New" or "Revised" License
649 stars 118 forks source link

Provide a template for Readme.md #683

Open jayoung-lee opened 3 years ago

jayoung-lee commented 3 years ago

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:

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 commented 3 years ago

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

kwalrath commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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. https://github.com/dart-lang/site-www/issues/2851 is where we're tracking the kinds of things we want to recommend.

jayoung-lee commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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.