I usually structure my READMEs like this:
The structure and content might vary depending on the project but that's the default "template" I use when I write a README.
I like it that way because users just need to take 5 minutes to read it and know what's what.
I like this as a standard, but I'd make a few quick changes if I were managing a very grand-scale project:
Move the license out to a separate file (Since it's not 100% necessary here, and Github and the like typically recognize a dedicated license file and have an easy link to it on the project page.
Have a very broad architecture/design section (probably after everything else), if the project isn't absurdly complex. This can give potential contributors a jumpstart if they want to help, but are having trouble putting together an overview of the file structure/software design. Obviously the trouble here is making sure it isn't too big for a readme.
I actually put the full license in a dedicated file and the "license" section of the README only contains a link to it. That's probably a bit redundant but it's an old habit from the time when GitHub did not include the license in the project page header.
That's usually something I put in the full documentation to keep the README more lightweight and free of unnecessary technical details.
Very useful, merci!
Hope some of this info adds to the discussion.
Often a gif can be super-helpful to show how a project functions.
An image can likewise provide benefit.
Logos or other images are also nice, they make the document more fun and less of a pain to read.
Also, people often like the "shields" to show numbers like num downloads/week or tests passing.
Happy to add to the discussion further.
Mac app I like to use, Giphy Capture, for making gif's
I like to think of a README very much like a college essay. Very formulaic, with a rigid and proven structure, with the intent of getting your idea across as quickly as possible.
While I am by no means an expert (or even really that great at following my own guidelines), here is the general structure I tend to stick with:
My main point to all of the stuff above is that your README should be a springboard to everything that anyone needs to know about your project. It should primarily work to get new users intersted in trying it out, aid existing users in getting to the right channels for help, and hold the important bookmarks that maintainers will keep coming back to. And above all, Your README is not your documentation, but it should link out to the relevant pages in your full documetation whenever possible.
That makes a lot of sense, and I would have probably fallen into the "Your README is not your documentation" trap if you hadn't point it out that clearly. Thanks a lot!
You're welcome! It's definitely a temptation to use the README for documentation, since it is right there and Github displays it nicely for you. But dumping full docs into a README is just going to make it too huge for a new user to easily scan and they will leave disinterested, and it is too difficult to navigate for existing users to easily find what they need.
Github's Wiki is just as easy to use and gives you proper navigation for small, flat documentation needs. For larger and more complex docs, it's probably better to keep your markdown in the project and integrate it with a static site generator1, so that the release of the project also publishes the docs to Github Pages or something like that. Either way, it's better for everyone than putting it in your README.
Orchid is a great choice of SSG for documentation. It can generate full Java or Kotlin API docs along with wikis and blogs and publish it all to Github Pages automatically, and it integrates seamlessly into your Gradle build
I always thought of README as a quick look over a project: what is it about and how to set it up quickly with some examples and a link to the documentation in case I need it. In this area, after a quick look on yours, I think it does it perfectly.
This article is pretty good about about the structure of README files: medium.com/@meakaakka/a-beginners-...
It also contains a template that you can reuse.
I especially like it when the contributors with avatars are listed at the bottom. It adds a great human touch.
Conciseness is key. My experience of READMEs has been when I need to learn something and being able to pull out the essentials. I think the README you linked is way too wordy and would suggest trimming it down.
Writing README along side with source code/feature development.
If you separate README development from source code development, you're doing it wrong.
Treat README like source code, it's an art.
So the answer is: it actually depends on the project itself.
Here is a really nice Readme Template
how do you guys think that we could improve our README ?
This may seem to be a weird question to ask, but it is not and here is WHY.
I am sure you have noticed that a lot of technical documentation is poorly written and frustrating.
Why is it so?
As it turns out, writing for users is hard work.
When you publish a project, it's because you are passionate about the topic.
Once you are ready pushing the "publish" button, you have learned even more about it, you know all the jargons, the implementation details, ...
The danger to write for you instead of writing for your users is very much present, and avoiding it is hard.
It would have been easy for me for example to write something like "Oh and by the way, don't forget to add the Gradle plugin portal in your settings file if you need too". And then my target audience (who is not ME) is like: what???
This is why I was interested by the wisdom of people that faced the same problems.
Thanks to everybody for their replies!
I use this as a rough template for many of my projects:
I also love adding shields:
We're a place where coders share, stay up-to-date and grow their careers.
We strive for transparency and don't collect excess data.