The PostgreSQL documentation and the limitations of community

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.

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.

https://www.postgresql.org/docs/current/pgcrypto.html

The page contains the documentation of many functions, all of which raise the following error by default when you run them: No function matches the given name and argument types.

It turns out you first have to "install" them by running "create extension pgcrypto", which is obvious to someone who already knows postgres modules well, but not to anyone else, and isn't mentioned anywhere on the page!