And don't forget that there are valuable volunteers who are likely to go elsewhere if too many new rules are added that they don't want to live with.

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.

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.

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.

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.

https://www.postgresql.org/about/sponsors/

Also, I think it's important to note that a lot of contributors aren't volunteering their "free time", they're being paid by some other employer to contribute to PostgreSQL as part of their job:

https://www.enterprisedb.com/blog/importance-of-giving-back-...

It isn't for contributing into a pot of money allowing some central PostgreSQL committee to hand out money for other things, like hiring people to do documentation.

From rough memory of an informal discussion with one of the members involved in the PG sponsorship area a while back, they had something like several hundred thousand US$ sitting around mostly unused.

The real problem is proposing something like this, and getting it okay-d. Seems like a tough (political) challenge.

There is a PostgreSQL core team (https://www.postgresql.org/developer/core/) that is a kind of steering committee, but does not make decisions concerning development. It consists of people from different companies.

The people who develop PostgreSQL are mostly hired by companies that have a commercial interest in the database and usually sell consulting, support, training, products that need PostgreSQL and customized closed-source forks of the database software.

There is no single authority in the PostgreSQL project. Decisions are made in mailing list discussions, cumbersome as that may be. The ultimate authority over the code is wielded by the committers (https://wiki.postgresql.org/wiki/Committers), which are highly trusted core developers who work for different companies. Development is slower than it might be with a single central authority, but that also part of the reason for the high software quality that PostgreSQL is known for.

Quote from Haas:

> But if on the other hand I propose some change to documentation that has existed for a long time, or some kind of structural change, there's a lot more room for disagreement. Because the change isn't strictly mechanical, the right answer is a lot more subjective. And because it's a change to existing content rather than the addition of new content, many more people will be familiar with it and have opinions on how it ought to be changed, if at all. Consequently, even when some developer does take time away from writing code to try to make some larger change to the documentation, it's often an uphill battle to get anything done, and people typically have to be content with small improvements.

Honest question: do PostgreSQL engineering decisions have the same dynamics as what's described here for docs decisions? If not, what is different about engineering decisions versus docs decisions? Is it just that engineering decisions can be literally benchmarked whereas docs decisions do not seem benchmark-able? Are there any other potential explanations for different dynamics between eng and docs?

If it does indeed just boil down to "docs are not benchmarkable" then I would suggest otherwise. You can create docs benchmarks. They won't have the rigor of engineering benchmarks but they at least establish some notion of docs quality and facilitate more targeted discussions during docs reviews. E.g. when there's a disagreement between an author and reviewer the author can say, "what docs benchmarks am I not following here?" The power of that kind of interaction is that you often do realize that the docs benchmarks are incomplete and some new dimension needs to be added to them. Or do the PostgreSQL contributor docs already have some guidelines along the lines of a "content quality checklist" and it's still not working?

A rigorous effort to survey the PostgreSQL community and get a deep sense of what the overall community considers "high-quality docs" can itself be a super insightful experience. Different developer communities often need / want a different focus in the docs. That can be the foundation for a fairly authoritative docs quality checklist.

Another thing that I'm very interested in, and will need to think through deeply some other day, is this notion that once you publish a doc, you can't touch it. It happens all the time and it's really weird.

While I think updating reference documents lends itself to subject matter experts (especially in a project where this approach is already successful), I think structuring them can be separated and given to a technical writer with more technical expertise or a developer with more documentation expertise.

We in infra-ops can give you more details about how our database clusters are designed for resilience, security, safety than you want on more levels than most people in the company know exist. We also have reasoning for all of this available. This is really good to have for customer question sets during sales.

However, this doesn't tell a developer how to connect his spring boot thingy to it, and how to connect and manage his service well. In fact, 80 - 90% or more of the things we know about our database are not relevant to a simple small-scale application running queries on it. And quite a lot of the issues you can have with running your application on a rock-solid database are entirely not relevant at a DBA level. Like, the database doesn't care if your DDL modification is backwards compatible.

And that's something we're currently learning together with a foundation team at work. They are documenting on how to use it well from their side, we're learning about easy mistakes to make and document those, and help with the actionable documentation. And in hard cases we kinda have to talk what's the plan, because it's usually not smart from a DBAs perspective.

And we have different angles of approach here. For example, we from infra-ops have setup a bunch of reusable and versioned template modules. These modules encapsulate all of the gritty consul/nomad/certificate handling and someone actually using our databases mostly needs to supply the module with the necessary environment variables their application needs. This in turn has been extended by a bunch of these teams to provide preset templates for spring boot, .Net, python, libpq so most applications just need to configure "I'm springdev and need to go to this database".

And currently another team is looking at building our own spring boot seeds, and/or using tools like cookiecutter or backstage to provide skeleton templates including most necessary boilerplate. We've started to maintain a template nomad job for simple applications as well.

With these things maturing, getting a simple service stood up can be done fairly rapidly if you know what you're doing. Setup the skeleton, throw out a couple of things you don't need, be done in an hour or so.

This however doesn't solve the initial problem. It's still tricky to know how to approach this stack and it takes time to either teach people how to approach this stack, or to condense all of this into simple how-to documents and/or workflows to get systems going.

https://documentation.divio.com/

We've been referring to it as the Divio system though, which appears to be the same thing.

LLMs are fit for this use. I think they could get trained on assembly language.

further, I think that at this point, the whole x86 spec is as impossible to analyze 'rationally' as any natural language. funny that it was created by dozens upon dozens of engineers in a rigorous and formal way; and the result is now mega complex. but I digress...

my point is to reconsider x86 spec as a 'natural' language which is the common "tongue" between software and PC hardware.

but by this point there's no expectation that a modern intel cpu is implementing the instructions in the way they were first created. it may well be emulating the x86 spec to the best of its capacity (another computer program "written" in 'microcode', a x86 virtual machine); so when thinking about x86 assembly spec as a language, the software computer is talking to the hardware computer; and if they agree the computer works. (so the socket and motherboard's buses can be understood as network devices xP )

finally, if I can come up with this (LLMs trained on assembly) so can any security researcher from any advanced academy or corporation.... meaning security researches NOT using LLMs like this ones I imagined are not doing their jobs correctly.