Ask HN: Why are FOSS projects beginner unfriendly?
I have been in the FOSS community since a few years now and projects either lack documentation or they don't actually support new comers to the projects. I faced an issue recently about docs too, it seems like big projects do not care about total newcomers, why is it so?
5 comments
[ 7.6 ms ] story [ 37.3 ms ] threadI will try to use a gross misrepresentation of a new-comer, but chances are they will ask trivial question that do not concern the project ( or are already answered ), some resources ( developer time ) will be used in favor of answering/guiding the newcomer ( who probably did not have search the usual sources before asking the question ).
Documentation is quite a pain to maintain, as it requires a good grasp of the English language ( mostly ), and quite a lot of empathy to figure out who the documentation is for. Additionally you have to make sure the documentation is accurate as the software change.
Returning the question: do you accurately comment the code you write for fun ?
Mostly, yes. But not when I am learning stuff, for eg, http://github.com/thewhitetulip/Tasks is a small app I built, there are next to no comments there because I was learning the language and thus didn't write much comments there.
I understand docs are pain to maintain, but a good FOSS project which is coding related (like a code library) is an amalgamation of the code AND the docs. The first preference goes to the lib with a great documentation.
>not as rewarding as aligning correct lines of codes
Yes, but when we look at the reward incorrectly! Yes, nobody will hail your contribution, but the fact that the project will be hailed because of the docs is not thought about mostly.
>but chances are they will ask trivial question that do not concern the project
This might not be a gross misrepresentation, but yes, sometimes there will be audience who doesn't fit in your project's audience, but what about the audience who fits?
I recently started learning a front end framework, I am totally new to a front end framework, I do not like frameworks, I learned and wrote a book on Go without using framework (https://github.com/thewhitetulip/web-dev-golang-anti-textboo...).
The docs are awesome of the project, I mean it. They teach the basics of the framework but _not_ how to use it in an actual project. Yes, if I know how to bind a variable via the docs it is great, but I do not know how to build a single page app just by reading how to bind a variable. It is a pre-requisite though.
For a framework which wants to be the top framework, I feel that there needs to be docs not just about the APIs but also about how to use it in a real project.
P.S: In the past, while commenting partially negatively about something, a person had taken huge efforts to crawl back on my HN/reddit comment history and calling out the names, I am intentionally leaving the name out of the comment; This is a general thing across all projects, not just the one I am complaining about.
The contributors need to be actively helpful on the chat list etc