One of the most salient features of our Tech Hiring culture is that there is so much bullshit. Everyone knows this. Each of us contributes his share. But we tend to take the situation for granted.
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!
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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!