DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’» is a community of 963,274 amazing developers

We're a place where coders share, stay up-to-date and grow their careers.

Create account Log in

Discussion on: How to write a good README? #discuss

Collapse
 
converge profile image
JoΓ£o Vanzuita

how do you guys think that we could improve our README ?

Collapse
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author • Edited on

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!