3 ms·

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

by dvhh 10y ago

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 10y ago
>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-textbook/ 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.

by dvhh 10y ago

thewhitetulip 10y ago

>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-textbook/ 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.