Define goal of a Standard Readme

[davidak]

This project readme sais:

Standard Readme is designed for open source libraries. Although it’s historically made for Node and npm projects, it also applies to libraries in other languages and package managers.

My goal, why i contribute here, is to have one ressource i can recommend to people that ask how to write great readmes. (right now i started an initiative to standardize the readmes of projects in my company)

I think a spec will not be that ressource, but it is a strong foundation to build on. I would compare it to the CommonMark spec, that probably most people who use Markdown on GitHub (that is actually not even CommonMark but GFM based on CommonMark) havn't read.

Some people might like a CLI generator programm, i would prefer an interactive website.

So i would like to define the goal wider, something like:

Provide a standardized readme template for open source projects.

It should be usable for most projects on github. For example:

• desktop software with GUI, for example https://github.com/atom/atom
• software with CLI, for example https://github.com/ansible/ansible
• software libraries, for example https://github.com/requests/requests
• websites, for example https://github.com/elementary/website
• texts and documents, for example https://github.com/seriesseed/equity
• datasets, for example https://github.com/zalandoresearch/fashion-mnist
• fonts: https://github.com/theleagueof/league-spartan
• 3D objects, for example https://github.com/sparkfun/3D_Models

It can be questioned if following a spec makes a better readme. https://www.makeareadme.com/ for example sais "Every project is different, so consider which of these suggestions apply to yours.". A spec and badge may implies that you SHOULD follow it and might degrade people or project that don't. Maybe promoting a guide and TEMPLATE would be better to reach our goal and have the spec only in background like CommonMark?

We also need to define the audience of a readme. I think that will be users and (potential) contributors. (users of a library are probably developers, users of desktop GUI software might not)

So i invite you to state your personal goal, then we can see if it makes sense to collaborate (#82) in a combined efforts.

@RichardLitt from https://github.com/RichardLitt/standard-readme/
@noffle from https://github.com/noffle/common-readme
@zcei from https://github.com/zcei/standard-readme
@dguo from https://www.makeareadme.com/
@PurpleBooth from https://gist.github.com/PurpleBooth/109311bb0361f32d87a2
@bevry from https://github.com/bevry/projectz
@davidbgk from https://github.com/davidbgk/open-source-template/blob/master/README.md

And everyone else who want to get involved.

(i choose this repo because it seems most complete)

[RichardLitt]

A more concise definition of this project might be:

Standard Readme is an open source specification for how to structure READMEs for code modules.

This covers what I need; templating (follow the spec), and how to write a basic README. Your mileage will vary depending on your use case; this spec is meant for code packages, and generally not for things like websites, text-only repositories, and so on. I disagree that standard-readme "should be usable for most projects on github" - or, at least, that's not my goal here.

If you want a resource for how to write a better README, focusing on content instead of structure, I would look at @noffle's art of README. It's more eloquent.

[davidbgk]

I like the idea of a template repository to quickly fork the given repo and start my new project from there.

[RichardLitt]

The generator does that, @davidbgk: https://github.com/RichardLitt/generator-standard-readme. I've set up repo templates before, too, like this one for @orbitdb.

[davidak]

I disagree that standard-readme "should be usable for most projects on github" - or, at least, that's not my goal here.

great, that's exactly what i wanted to achieve with this issue. can you add the definition to the projects readme and the spec? you could than also remove "it’s historically made for Node and npm projects" from the spec and just have that information in the Background section of the readme. When you have stated the project goal clearly, you can close this issue.

Like i said, i want to work on a more general readme template for any kind of open source project, so i will mainly try to improve make-a-readme. Feel free to join the discussion there. Although i don't care following this spec, my further work heavily depend on it, so the work is greatly appreciated!

[RichardLitt]

I like how it is at the moment. Thanks for your help.