Open Web Docs is a potential model to draw inspiration from regarding funding: https://openwebdocs.org
Presumably, PostgreSQL has leaders who are responsible for steering the ship. If the project is going to succeed long-term, those leaders have to find ways to keep their contributors happy while also creating an organizational structure that leads to good docs. Easier said than done, I know, but it really is as simple as that.
Sorry if any of my comments came off naive or obtuse when it comes to open source dynamics. But the reality is that you need good docs, and I'm just trying to give an honest assessment from my experience of the conditions that lead to good docs.
Sorry if any of my comments came off naive or obtuse when it comes to open source dynamics.
If you want that apology to be meaningful, you should learn something.
When you're talking about a highly successful open source project that has been going for more than 3 decades, it is beyond ludicrous for you to say, "If the project is going to succeed long-term..." It already has succeeded long-term. And you would be better off figuring out why it works rather than lecturing about how it must work.
When you talk about "a potential model to draw from" for funding, please note that I've been involved with open source for about a quarter of a century. I've seen a LOT of funding models attempted. Mostly they run into one big problem. And that problem is that adding funding creates bruised egos because people say, "Why is he getting paid when I'm not?"
The one funding model that DOESN'T have this problem is when a company decides to pay its employees to work on features that it wants in the project. Now there are no bruised egos - the money comes from the company and it is clear why one person gets paid while another does not. There are still challenges with this model - employees are under pressure to get their contributions accepted whether or not the project likes them - but we've learned how to navigate those.
But now we're left back where we started. Companies who hire core developers don't generally need comprehensive documentation - they build internal documentation straight for their use case. So comprehensive external documentation is hard to find. Sometimes you'll wind up with things like an excellent introductory tutorial like https://docs.python.org/3/tutorial/. Usually, you don't. And generally it is hard to simply pay someone to take care of it for you.
> When you're talking about a highly successful open source project that has been going for more than 3 decades, it is beyond ludicrous for you to say, "If the project is going to succeed long-term..." It already has succeeded long-term.
Yes, your reaction here totally makes sense. Feedback acknowledged.
> If you want that apology to be meaningful, you should learn something.
I have re-read my earlier comments and I feel that you are being more hostile to me than is justified. I do not think you are adhering to HN's code of conduct guidelines for comments: https://news.ycombinator.com/newsguidelines.html#comments
> you would be better off figuring out why it works rather than lecturing about how it must work
This doesn't seem fair. The original post is about the limitations of the PostgreSQL docs. Docs have been the focus of my career for 10 years. I have experienced and analyzed docs problems in many contexts: small orgs, large orgs, open source, closed source. I made an on-topic comment about ways to resolve the problems that the PostgreSQL docs are facing. Is it the only solution? Of course not. But I totally have relevant experience in this domain and, just like you have a good idea about what generally works and doesn't work regarding open source funding, I have a pretty good idea about what generally works for creating the conditions that lead to good docs.
> So comprehensive external documentation is hard to find.
Again, I think the web platform space is relevant here. Web platform documentation could easily devolve into a tragedy of the commons situation. Yet MDN does exist and is an amazing resource.
Paragraphs 4 to 6 of your last comment seem to be arguing that hiring TWs is not an option for PostgreSQL. That is totally understandable. On another day maybe we would have arrived at that understanding on friendly terms and would have had a constructive conversation about how to create good docs when hiring TWs is not possible. But it's clear that my ideas aren't welcome here so I'll just stop now.
If someone gets weirdly hostile and condescending towards you on HN (sadly not uncommon), I recommend that you try to just ignore them and keep contributing. I’d like to hear what you have to say.
Hey, I enjoyed your comments and appreciated your experienced view.
And, that person is being overtly hostile - I can only describe their behavior as making shit up in order to justify picking a fight and talking down to you.
I don't think you should take anything they say to heart - flag and move on at this point.
Presumably, PostgreSQL has leaders who are responsible for steering the ship. If the project is going to succeed long-term, those leaders have to find ways to keep their contributors happy while also creating an organizational structure that leads to good docs. Easier said than done, I know, but it really is as simple as that.
Sorry if any of my comments came off naive or obtuse when it comes to open source dynamics. But the reality is that you need good docs, and I'm just trying to give an honest assessment from my experience of the conditions that lead to good docs.