News for hackers. Stuff that matters.
Re:Libui: a portable GUI library for C by dkersten on Sunday May 20, 2018 @05:31AM (#17111985)
I completely agree. Besides, how can you submit a pull request for documentation when there’s no documentation for you to understand the code with? I say that as someone who spent a week trying to figure out a project recently, including reading the source code to figure out how it worked, submitted a pull request to improve some of the code and wrote a beginner getting started tutorial. That is, I have went through the effort and it really was a lot of effort to the point where I’ve been meaning to finish a followup article but just lost all energy for the project and moved onto other things.

Documentation is so important if you want to get people interested in your project. Personally, I value good documentation above features because without documentation I may never learn how to use your features and may never get started using the project. If I never use your project then there’s zero chance that I will contribute. Or, like above, I do, but run out of steam really quickly and lose interest.

Re:Libui: a portable GUI library for C by boomlinde on Sunday May 20, 2018 @11:37AM (#17113192)
> 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.

Re:Libui: a portable GUI library for C by dkersten on Sunday May 20, 2018 @12:49PM (#17113621)
It’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).

Re:Libui: a portable GUI library for C by boomlinde on Sunday May 20, 2018 @05:49PM (#17114946)
You'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.

Re:Libui: a portable GUI library for C by bocklund on Sunday May 20, 2018 @01:52PM (#17113938)
> 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.