Hacker News Reader

Comment by sidlls | Hacker News Reader

Open source is most certainly broken, and not just due to the various financial, freedom and security issues these two articles focus on. My biggest peeve: documentation is often minimal (e.g. API docs only) or filled with useless toy examples that are effectively just rephrasing of API docs.

The entire underpinning of free and open source software is silly: software in this context isn't an academic pursuit producing knowledge that should be freely shared to our collective advancement as a civilization. It's a hammer, a wrench, a table: in short, a product. That fundamental category error made by our community is the source of all the problems with F/OSS, financial and otherwise.

View on HN

You know, one of those terrible aspects of open source is that if you see a lack of documentation, you can just contribute it yourself. Good luck contributing new docs to literally any proprietary product.

This implies that the issue is due to being open source. The majority of closed source software, especially in house software, has minimal or nonexistent documentation. If there is any, it was likely done once at the start of the project and never updated since.

I've been a consultant for over 10 years. I always make sure to ask for access to any documentation for systems I'll be working on. I think I've gotten significant (out of date) documentation maybe once. This isn't an issue stemming from being open source.

I agree with what you say, but FYI docs is one of the easiest yet most valuable thing a person can contribute. As a maintainer, I wish I had more feedback and contributions to the docs!

As someone who wrote large parts of the docs for a project: The reason that I imagine few people do it is because if you get involved with the documentation, you will be on the hook for tracking the library closely and keeping the documentation up to date; there will be an implicit, external pressure that the documentation continues working.

That becomes a lot of work very quickly, so I tend to only get involved in libraries that will quickly hit some kind of stable maintenance mode or in which I have personal stake and thus just need to polish up my own notes for how to get off the ground.

Updating docs should be part of the responsibility of adding a new feature, just like adding tests and making sure no existing tests are failing.

You're describing two legitimate worlds, the Ivory Tower and the Marketplace, let's call them for short, but I don't think the error is conflating them. I think the error(s) arise in the intersection between the two realms. The Internet was a-commercial or even anti-commercial at first (having gestated in the Ivory Tower) and retrofitting it for commerce and industry has been, um, a wild ride. Kind of a gold rush.

Copying and running code is (effectively) free, developing, maintaining, and auditing code is still expensive. Folks who want to use software without paying the costs get what they pay for, eh?

I feel that if there's anything the community is doing wrong, it's in the emphasis on new and shiny rather than mature and stable. I feel we should be entering a "contractile" stage of (global IT) development, with consolidation and convergence of software and hardware replacing the wild burgeoning and rampant growth of complexity.

"Like, complexity is an existential threat, man..."

Writing documentation is boring, adding new features is more fun to do.

Someone working on open source to have fun is more likely to invest their time in more features instead of better documentation.

Here companies or users like you could step in and contribute better documentation or pay the original authors to improve the documentation.

Why on earth would I labor for free on someone’s vanity project, no matter what utility it provides otherwise? And why would a company pay a person who has already shown he or she does not value their own labor in that way?

You want good documentation from an (ostensibly hypothetical) piece of open source software that you use. But you will neither pay for nor contribute better documentation.

You see where the problem is, right? I'll give you a hint, it's not the developer...

No, it absolutely is the fault of the developer, both for poor practice of the craft and for contributing to a toxic, exploitative labor environment by giving away his work for free.

You don't have to use his project then.

Is someone release code because he liked to code but don't write any docs because that's boring, that's perfectly fine. No abuse there. The abuse is when you requests docs for free.

You get what you pay for. There are plenty of documented/supported libraries out there to buy in place of open source software.

Wait till you read documentation commercial projects have. Our one is super quick to read, as we don't document at all.

Reply on news.ycombinator.com