It's okay to have that attitude about tutorials, and guides to internals, and other satellite docs, but not core documentation (reference manual or spec).

I suppose all I really wanted to say was that maybe people in general should open their mouths / comment boxes less. (Yeah my comment sucks, doesn't listen to its own advice...)

For example, what might have been an innocent question for one person is actually an annoying nag to somebody else, because they've been answering that sort of question for a long time and have built up an expectation for everyone else to do more research first. The person asking the innocent question doesn't know that they're the hundredth person to ask, so to them the response seems harsh and unkind. Someone observing the exchange from the outside is going to have their own judgments on the quality of the community.

The solution to difficult communication isn't to communicate less, it's generally to communicate more and that doesn't necessarily mean more conversations, because communication can take place in many different ways.

What would help even more is to approach communication with some level of empathy and compassion, and accountability for how you react to those reaching out to you (or those you're reaching out to, of course). If it always seems difficult and sucky then you need to understand why you continue to see it that way, why you get frustrated, and what you can do for your part in that communication to make it more pleasant for yourself. And then make that position clear so there's no misunderstanding of intent.

A large part of communication in those terms, and at the scale we're looking at here, is setting clear boundaries on how you wish to be communicated with and how you'll do your best to respond. It's not useful to act out and complain and moan because nobody can guess what it is you want from them.

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.

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.

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).

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.

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.

I agree with your point about reading the signals of which projects are probably the best.

But with great power comes great responsibility. It's entirely possible YOU are the person who makes this project great, just by the Butterfly Effect of getting the documentation good enough that the next person who comes along will be willing to choose this and push a little harder, and so on.

You're not forced. You're not obligated.

But if you show up, you get to make decisions.

That's not true with documentation. the decision has already been made. if you show up later and write the docs then you're just hoping you interpreted the decision correctly and aren't misleading people.

If there wasn't an intentional design decision, then who knows if the behavior you try to document lasts beyond the current version, who knows how quickly that documentation is out of date. (Likely if a project doesn't care about documentation before you arrive, they might not likely care about stale documentation either.)

One of the ways it can be done is to start independent documentation effort, without even considering to merge it to project repository. Then, having these "draft" docs, it will be easier to make "official" documentation. Even blog posts "how to get started with libui" can be useful. This project looks very promising, like WXWidgets, but in C and not C++, for this reason it has lots of language bindings already.

People that know C should be able to read and understand the interface file at:

https://github.com/andlabs/libui/blob/master/ui.h

The function / variable names are informative enough. There are examples which should get you started at:

https://github.com/andlabs/libui/tree/master/examples

Even if they would add comments to the interface files (that may be used to generate docs), it will not add much value if it will become as follows:

  // Set window title. First argument should be the window and the second the title as a string
  uiWindowSetTitle(uiWindow *w, const char *title);

They would have to be written with documentation in mind, which distracts them from their primary purpose: catching bugs. Trying to understand Monocypher from just its test suite¹ for instance would be a pretty bad idea. That test suite is top notch at catching bugs, but it sucks big time at documenting Monocypher.

https://github.com/LoupVaillant/Monocypher/blob/master/tests...

If you don't already feel the project has value, I doubt the availability of documentation would sway you.

>I shouldn't be forced to make a contribution to a project if I just don't think it's doing everything right.

You're not being forced to do anything. We're just saying different people have different priorities: what's important to you might not be important to other people. Who knows? Maybe the programmer thought the header file was sufficient. It might very well be more than enough for his own needs. Instead of saying "somebody should write detailed documentation", people expect that you will be that somebody, since you're the one who raised the issue.

You have no obligation to contribute to the project, but if you think it is lacking in some respects, making your own contribution is the most obvious way forward. So you give some constructive criticism, and the response is a suggestion for a way to address it. No one is telling you that you are obligated to contribute, and no one is calling you out. You want work done and you aren't compensating anyone for doing it, so the only way the work will ever be made is if some actual contributors' interests happen to align with yours, if you become a contributor yourself or if someone is willing to work for you without compensation.

As it stands with this library, there is an open master issue to improve the documentation. The author has acknowledged the problem and is accepting pull requests to improve it. The general advice to improve the documentation is at this point is not adding any information to the contributors of the project, because now it's only a matter of actually documenting the issues in the github ticket system and for people to put in the work. The suggestion to make a contribution yourself makes even more sense given this context.

> I shouldn't be forced to make a contribution to a project if I just don't think it's doing everything right.

You use the words "obligation" and "force" very loosely throughout your post. It's not adding to your point that you blatantly misrepresent the suggestion to contribute the work that you want to see put into an open source project as some sort of coercion or shaming.

I think that it's better to be clear about it. I'd find it rude if someone said "thanks for your feedback" without intending to seriously evaluate or address it. If submitting pull requests is the best way to get work done in a project, its maintainers should be clear about it.

If you don't have time for that, its not the problem of the authors.

That said, were this a commercially driven enterprise, the lack of documentation is an issue. But, true fact, most open source projects can immediately benefit from the involvement of someone, anyone, willing to update the docs .. so, be a hero: submit a PR, someone.

Have you checked this: https://github.com/andlabs/libui/blob/master/examples/contro... ?

Secondly, exams code can get outdated just as much as human documentation. I've lost count of the number of times I've gone to compile example code only to find it doesn't work because of API changes or such like. I've also had example code crash my whole machine because it effectively created a fork bomb (thanks Microsoft for that one!)

So the arguement of example code Vs documentation isn't a mutually exclusive one.

In fact the main open source project I'm working on automatically generates it's documentation to help ensure its accuracy - and I know for a fact that I'm not the only person to do this.

Give me an example over documentation any day.

This is usually how I work. I only look for the documentation when it does not work.

The C API documentation includes a ton of example code: https://ffmpeg.org/doxygen/4.0/dir_687bdf86e8e626c2168c3a2d1...

In addition to having both a man page and a --help option, The FFmpeg CLI tool has very thorough documentation: https://ffmpeg.org/ffmpeg.html

I don't understand how FFmpeg could in any way be considered to have no documentation and no code samples.

"I shouldn't be forced to make a contribution to a project" OMG.

Anyways, the whole argument doesn't matter and is totally irrelevant. Serious teams/engineers will analyze the code, consider using it, and then assign developers to help out with documentation if it provides sufficient value proposition. And thus the cycle of OS improvement continues.

Yes, documentation would be nice, but code quality is 100x more important. 100 times out of 100 i'll pick the project with better code quality over better documentation.

BTW, clear, understandable code and APIs is an example of good code quality. And of course, well written unit/integration tests usually provide sufficient example code.

In my opinion, good documentation has three parts (four if you include a tutorial too):

First is a document explaining rationale, high level/big picture design, tradeoffs, when to use what. Usually a prose document with some sample code snippets where appropriate. Second, example code showing how to solve different use cases. Finally, an api reference (often auto generated from docstrings).

Different projects need different levels of each of these. For example, a relatively simple library might get away with a few short paragraphs for the prose documentation and maybe the api reference is literally just listing the public functions (if the names and parameter names are descriptive), this can be generated without any additional markup. If the api is complex, then it may need some explanation. Or the text documentation needs to be more detailed.

Obviously I don’t expect this from everyone who release some code online. For small code snippets, I’m happy with a commented example use and appreciative that you released the code at all. However, don’t be surprised if your code doesn’t get used then and if you want me to contribute, then I need to understand your project and without documentation I can’t do that. If I don’t understand your project, I risk that any PR I do is wasted effort and my time is limited (but I’ll happily help projects I use out regardless, where I can. I may need some guidance though)

One of the most beautiful C codebases I’ve seen - the SSH IPsec stack - had the most succinct yet comprehensive documentation. Linux kernel has virtually none of the latter but the quality is still very high. Then there’s something like Miranda IM - complete clusterfuck of the code, but really well documented. A lot Java code is that way too, but also with documentation rehashing trivial facts rather than explaining anything.

However, what does seem like a sign of a good code is longer intro comments in header files that explain the design rationale and how things fit together in general. It’s basically a level up from verbose API description, but when done right it makes the API obvious without any further detailing.