Hacker News Reader

Documentation gives at least the functional, if not detailed, requirements for what the code is supposed to do (as well as not do). "Submit a pull request for documentation" is basically "please write down the set of requirements for what you think I might have coded up here and send them to me" which is an absurd way to do engineering, regardless of considerations of licensing and compensation structure.

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

Yup, here is a good example of that in the wild: https://github.com/mholt/PapaParse/issues/495

The README says right there that they haven't found a good autodoc tool for C and that their API instability makes it burdensome to maintain documentation right now; calling them bad engineers for that is a bit much. Their only "mistake" is being a project for which outside enthusiasm has far outpaced its progress.

People suck at communicating, but people want to communicate. People love to complain more than they love to fix things. A lot of the time a complaint is half frustration, half trying-to-be-helpful-suggestion. Sometimes it's just people complaining about other people complaining (like the "fix it yourself" crowd or the "didn't you reflect before posting that the issue of X is already a known concern?" crowd) but this just goes back to people wanting to communicate.

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

It's a hell of a lot easier to be negative or express a frustration than it is to put the energy into a positive, constructive conversation. It's not an easy problem to solve because the different parties to the conversation have different experiences and are often unaware of the situation for the other people involved.

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.

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.

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

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

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.

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

Decisions are made by those who show up.

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.

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

Plus, you are interpreting whether or not a decision was even made. Maybe it was an implementation detail that leaked out, or maybe the decision is still left as a TODO in the backlog somewhere.

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

Isn’t that what the PR is for? one would assume “send a PR for docs” means “i’ll review before merging”. it seems like nobody wants to write the docs and the author already wrote the code so why double tax him when he is doing this all for free?

It's hard to "just send pull request" with such core and large aspect as documentation. You can work on your own and submit bug fixes, improvements, more examples and clarification for existing docs, but making documentation from scratch requires communicating and planning together with project authors. And you should know the project very well to write docs, at level of core developers.

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.

Many people have no problem using libui. There are even many bindings available that people use some of which have documentation. I was able to start using libui instantly, but mostly because I already have experience using other GUI libraries.

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

What I think is more important is adding tests etc. Tests can then also serve as a kind of documentation.

> Tests can then also serve as a kind of documentation.

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

>I do this because I feel that the project has something of value and can be improved

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.

> It's absurd to think that I should just pick up a random project and be obligated to make it better, and that I should be called out for giving advice on how I think a project can be improved.

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 it breaks down to people skills. There is one group of people looking to use the lib for a project and another group that would be interested in contributing. Saying make a contribution to people not in the latter group is a bit rude. A better response would be to thank them for their feedback and mention contributors are welcome from those that are willing.

> Saying make a contribution to people not in the latter group is a bit rude. A better response would be to thank them for their feedback and mention contributors are welcome from those that are willing.

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.

I see it completely differently. This is a fantastic body of work, and as far as documentation goes: read the source.

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.

I am quite oposite, I want example code using as much aspects of library as possible - sort of "a picture is worth a thousand words". Documentation is nice to have, but I personally consider a well written code a documentation, and it doesnt get outdated ;)

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

Firstly, good documentation will include example code anyway. That's part of the course of documenting.

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.

Outdated examples can be mostly avoided by building them as part of CI and if possible running. Using deprecated attribute can even detect some of the cases when example builds but doesn't match recommended way of doing things.

Sure, but that would depend on project contributors doing that as part of their process. Which leads us back to square one on 'core documentation should not be something that has to be submitted via pull request.'

In an attempt to mitigate this, you could include the examples in your testing suite, at least to see that it still compiles properly. This is sort of standardised in the flow of Go, with godoc and the testing framework. Both uses examples from the same test files, producing standalone docs and testing them(at a minimum compiling them) .

This also happens in the Rust documentation generator. The code snippets in any piece of Rust documentation are compiled and run, and the assertions found in it will be reported if they fail. They're sort-of automatically part of the test suite.

Indeed, but we are talking about the lower end of the spectrum in terms of documentation (ie the arguement of what takes priority). If someone is considerate enough to include examples as part of their testing suite then you can probably bet they'd be equally thoughtful with their documentation.

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.

(Hint: I am trying to make libui's in-code documentation match the Go style, which no existing C-based documentation tool seems to do...)

The first thing I looked for (and found) was the examples directory.

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.

I work for many years with FFMpeg that has no documentation and no code sample, and it's okay for me. I prefer that the developers keep their time optimizing the code rather than writing documentation that needs to be maintained and become a problem when not in sync. My state of mind is that if it's open source then just read the code.

FFmpeg's C API has pretty good documentation: https://www.ffmpeg.org/doxygen/4.0/

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.

FFMpeg is not some random project - it's irreplaceable and very popular.

Well, the only way I get it to work is by searching up how to use it on Stack Overflow, so…

Then don't use the project. Good lord... the sense of entitlement is over whelming!

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

Documentation is part of code quality.

That's rarely been my experience. In fact, documentation usually exists because code quality is poor and it needs to be explained.

In my personal experience, examples do a poor job of explaining the reasoning behind something or the big picture behind something. It depends on the project, obviously, but often examples are fine for simple things but really don’t help with big complex things. Often they also don’t explain the trade offs or when you might choose a the various different options.

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)

From my experience there’s little to no correlation at all.

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.