Collaborate and consolidate

[davidak]

I was searching for something like this and found many ressources.

Maybe you can collaborate with the other projects and try to find a consent and consolidate projects to have fewer, but more quality ones. When you can't find a consent, work out the differences and state them clearly. (that's maybe something all open source projects should do?)

The most user friendly ressource i found is https://www.makeareadme.com/.

This project seams to be the most complete.

This Gist has a lot of stars: https://gist.github.com/PurpleBooth/109311bb0361f32d87a2

This text has also more star than this project: https://github.com/noffle/art-of-readme

This blog post is well written: https://rowanmanning.com/posts/writing-a-friendly-readme/

More:

https://github.com/matiassingers/awesome-readme#articles
https://github.com/zcei/standard-readme
https://github.com/bevry/projectz
https://github.com/noffle/common-readme
https://github.com/davidbgk/open-source-template/blob/master/README.md

[waldyrious]

I'd love to help out in such a consolidation. READMEs are the entry point for any open source project, so it's a very important part of the ecosystem that deserves a more concerted effort than a bunch of scattered initiatives.

[davidak]

@waldyrious great!

A plan could be:

1. see what other projects make different (other sections or order). look for previous discussion in issues, create new one if you found none.
2. have this project and the spec in good shape (currently "Standard Readme is designed for open source libraries" and JS background, it should fit most open source projects found on github. the spec has no version. i also see other small things to improve and clean up)
3. ask other initiatives to collaborate to consolidate their differences with this project and finally close their project in favor of ours (with link to this)
4. ask people for their opinion on this spec and improvement suggestions
5. i think https://github.com/dguo/make-a-readme would be a great place to present it and send people to, with general information what the purpose of a readme is and easy to use template
6. then we should find ways to spread the idea (badge, ask for stars on github for both projects)

We could also think about this initiative like CommonMark with optional extensions. So when no consent can be achieved, it can be an extension.

Maybe find a more precise name. This Spec should be for open source software projects. Other projects like Websites or Art (Games, Pictures, Videos) might also have a Readme file in a ZIP where they are delivered.

Do you have additional ideas or suggestions?

[waldyrious]

Thanks for the detailed plan. Some comments, number-matched to your items:

1. I can help with the implementation part of the plan, but this open-ended research part is beyond my availability. Other than that, yeah, I agree it's the necessary first step.
2. This is not very well defined. I understand it's just a suggestion, but we must make sure it's eventually specified as a set of concrete, actionable steps.
3. In my previous experience proposing similar joining of forces, project owners have been reluctant to close their project in favor of another one. Maybe we will have better luck if we propose creating a new organization which all merged projects' owners will be part of, and also allow a collaborative decision on the name of the merged project.
4. This is too vague to be actionable IMO
5. I'm not sure I understand your reasoning for this one. Can you expand a bit?
6. A badge would be ideal IMO. Asking for stars might work for promotion, but I'd prefer people to do it on their own accord.

[RichardLitt]

Hey @davidak 👋! Thanks for the initiative here. Glad to see more people interested in making great READMEs.

try to find a consent and consolidate projects to have fewer, but more quality ones.

This is incredibly difficult, mostly due to design implementations, which often aren't stated explicitly. For instance, standard-readme started out of a need to provide basic READMEs for many JavaScript projects. However, it doesn't really cover python packages that well, which traditionally use .rst files. This was a tradeoff I dealt with when I enforced Markdown as a format. I could extend the standard beyond .md, but I haven't - because it would take a lot of time and effort to figure out, and it wasn't a problem I originally had to solve.

There are also politics involved. For instance, https://github.com/zcei/standard-readme stalled, I feel, because it depended on a code implementation. I wanted something faster, so I made this spec, which doesn't depend on code to work - you can just read it. But by making this, I took some participation away from @zcei's repo, which I feel bad about, but which I needed to do at the time to get the runway needed to take this spec off of the ground. Actually, both of our efforts came from this issue, and depend on a lot of the conversation there. To move faster, I didn't ask a lot of permission from the people in that thread. The same could be said of @noffle's repo. He wanted to have more description - for instance, his background section - and was less worried about the skeleton of the README headers than about getting the main point across. @noffle also has a lot more experience than I do dealing with Perl READMEs, which is a community I know almost nothing about. We come from different perspectives, have different goals, and came up with different solutions to the problem of 'How can we make everyone have better READMEs?' (I'm also jealous he has more stars. But he is my friend and this isn't a competition, so it's silly to think about, but what @waldyrious says above in "project owners have been reluctant to close their project in favor of another one" is definitely true.) I also worked as the most active maintainer of awesome-readme for the past year or two, until I recently resigned because I didn't think I was doing much good there.

All of this is a long way towards me saying: thanks, but I am more interested in focusing on making this project better, when I need to. This is a labor of love - I'm not directly paid for this work, although it does help with my work at @mntnr.

You mention some specific things we could improve - for instance, adding a version number. I think more direct, actionable points like that are great. But I'm not sure I have a grand plan beyond small spot-fixes like that. Where there are other plans - for instance, finally getting around to building that linter - they are in open issues, and I would love help. Is there something you feel we should be doing that isn't already in an issue? If so, I encourage you to open one! :)

[zcei]

For instance, https://github.com/zcei/standard-readme stalled, I feel, because it depended on a code implementation. I wanted something faster, so I made this spec, which doesn't depend on code to work - you can just read it. But by making this, I took some participation away from @zcei's repo, which I feel bad about, but which I needed to do at the time to get the runway needed to take this spec off of the ground.

Don't feel bad about it. The reason was me being to ambitious in the beginning, and trying to account for a lot of different opinions in the discussions.

What personally made me stall was the endless discussion about the API section, so eventually I stopped proceeding on it, but still come back and copy the README content whenever I start a repo. So in these terms that "is enough for me" and I wouldn't have hard feelings consolidating projects with others.

The reason for a codified check originated from the original issue in standard. It's a linter, so I wanted to let people know whether they actually conform to the standard they chose for their README.
Maybe at some point I will have a use-case again that really requires linting a README, but until then no code is planned. (I should update my repo with this information 😆 )

[davidak]

@waldyrious i will compare sections from other initiatives and create issues with concrete, actionable steps we can discuss then.

3. Maybe we can find an organization that works to sustain open source projects that would like to maintain such a merged projects. For example i think of Free Software Foundation / Free Software Foundation Europe, @opensourcedesign, ... You probably know more.

I might not be the right person to organize such an effort, because i think i'm not good with communication and beeing empathic. I don't want people to feel bad or think we want take away their projects, but see the bigger goal to create a combined efforts.

4. spontaneous i think about the @elementary OS developers (they have good UI guidelines and design) and @opensourcedesign. You might know other people that might have an opinion on this and a background that helps to know what is important in design and open source projects.

5. right now, this spec is no place i would send someone that just wants to know HO TO CREATE A README. the linked site is a way better ressource, because it also explains what the purpose of a readme is and the template is editable, so you just can copy it into your project. A spec is a good foundation to build a more user friendly site. I just found https://opensource.guide/starting-a-project/#writing-a-readme whichs looks like a good guide to start. We should provide something that can be linked from there.

6. a badge already exists and about 1800 people use it on github. i wonder why this project has so few stars compared to the other ones, especially that gist.

it doesn't really cover python packages that well, which traditionally use .rst files

@RichardLitt it is now possible to use Markdown even for PyPI (i don't know for how long). psf/requests@eea96f9 When people want to use rst, they still can use the sections.

[dguo]

I am definitely open to collaboration, but as @zcei alluded to, I would expect there to be a lot of bikeshedding. While there is a fair amount of common ground between all these resources (which I think is a great thing), there are small details that I personally don't agree with but are also not that important.

@RichardLitt's points also seem quite challenging to overcome, particularly the one about different design implementations.

As a side note, thank you to everyone here for trying to make READMEs better and to @davidak for taking this initiative. Writing good READMEs is an underrated skill.

[kishaningithub]

Adding one more readme generator
https://github.com/generate/generate-readme

[RichardLitt]

At the moment, I am OK with standard README as it is. :)