
Ask HN: Why are FOSS projects beginner unfriendly? - thewhitetulip
I have been in the FOSS community since a few years now and projects either lack documentation or they don&#x27;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?
======
dvhh
As it is for even closed source project, documentation and support are a major
pain, and are not as rewarding as aligning correct lines of codes.

I 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 ?

~~~
thewhitetulip
>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](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...](https://github.com/thewhitetulip/web-dev-golang-anti-
textbook/)).

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.

------
itamarst
Some do - see [https://openhatch.org/](https://openhatch.org/)

------
meric
How would I make this project more friendly to newcomers?
[http://github.com/meric/l2l](http://github.com/meric/l2l) Is it a matter of
documentation?

~~~
thewhitetulip
One should be able to read the docs and understand things rather than have to
google every other thing.

The contributors need to be actively helpful on the chat list etc

