As we all know gitlab parses Readme.md and adds it to the very front of the project repository where it’s easily visible.
Now the point of discussion as the title suggests is, that can such an ability be used to give a head start to anyone new getting started with the project or not ?
Now as we know that there are many ways to design a README.md.
Some projects just put up the Wiki link their and some make it very much descriptive.
Now if we want to design a README.md from a newcomers perspective I want to ask opinions from project members on their thoughts about the Idea.
If they accept that this can be good for their project what might the design look like.
Typically, a README should not be overly complicated; it should describe what the project is, does, and why it could be useful to you.
Getting newcomers to contribute to a project should be part of the contribution guidelines; GitLab supports having a CONTRIBUTING.md in the project’s root, and will link to it in the project’s overview page.
The contribution guidelines should be friendly, clear, and set the expectations of the maintainers. My personal go to template for this is Nadia Eghbal’s contributing-template, which we adopted for GLib and GTK.
We recently rewrote the readme files for Tracker and Tracker-miners, and I had to think about who the audience of these files was.
Some people discover the project because it appears in top and they want to know why. They wouldn’t otherwise care what Tracker does or what it can be used for, they are just looking for support to deal with a configuration issue on their machine. Do we consider these people newcomers? I think they’re an important audience for the README file, either way.
Anyway, for me the goal of rewriting the README was:
give a short, high-level explanation of what the project is for
avoid duplicating info that can be found elsewhere.
provide useful info on how to build and test the code (we previously only had info on how to install it into /usr, which is normally the wrong thing to do)
I’m sure more improvements are possible, but I think it was a reasonable starter.
I agree with the sentiment: we have GitLab now with MarkDown, so we should use it. I’ve done this for most of my projects as well (for example in the seahorse repo). I do agree with @ebassi however that we shouldn’t overdo it: badges with the CI status are redundant (and download images from the internet).
I think it’s a useful thing for new contributors: for example, people who come to my project to fix a translation error should be immediately pointed to our translation project. That prevents the whole awkward discussion of “yeah, thank you for this MR with a translation fix, but I have to close it since that’s not how do it at GNOME”
If I may toot my own horn… librsvg’s README.md, and its CONTRIBUTING.md / COMPILING.md were carefully written after contracting with Sumana Harihareswara from Changeset to do a review of friendliness to newcomers. It has worked very well! Feel free to use those files as a basis for other projects.