3 ms·
> Besides, how can you submit a pull request for documentation when there’s no documentation for you to understand the code with? By reading the code? You're p
by boomlinde 8y ago
> Besides, how can you submit a pull request for documentation when there’s no documentation for you to understand the code with?
By reading the code? You're posing it as some kind of impossible paradox, but with the full source code available you have a pretty readable specification of how it works.
- dkersten 8y agoIt’s very hard to understand an unfamiliar codevase. The documentation doesn’t have to be super-fine grained, it just has to give a helping hand in understanding the high level design and use of the code. I can usually figure out api parameters, but that’s often not enough to use the code and certainly not enough to document it. Don’t get me wrong, I’m talking extremes here and I don’t expect a lot from someone’s passion project in terms of documentation effort, just a little helping hand if you want me to have a good experience (which is a prerequisite for me to care enough to contribute).
- bocklund 8y ago> It’s very hard to understand an unfamiliar codevase. I agree - the high level design and stuff is hard. But being a user and having the code allows you to document 1. Function level documentation including inputs, outputs. Even if you don’t understand how it fits in to the bigger picture. 2. Provide examples of working code (recipes) with some explanation of what it does.
- boomlinde 8y agoYou're going off on a tangent. The question wasn't "is it harder to figure out what the code does by reading it than reading well written documentation?", it was "how can you submit a pull request for documentation when there’s no documentation for you to understand the code with", and the obvious answer is: by reading the code—in fact, that's ongoing work by some of the project's contributors.