Haas: The PostgreSQL Documentation and the Limitations of Community

[Posted June 14, 2023 by corbet]

Robert Haas looks at the advantages and disadvantages of how documentation for PostgreSQL is written.

The strengths of this process are also its weaknesses. A developer is, by definition, someone who spends the majority of their time doing development, which is to say writing code. Updating the documentation becomes a task that must be completed so that the code one has written can get committed so that one can move on to the next project and write some more code. If a change to the documentation would be beneficial but is unrelated to any particular patch, it's not likely to get done.
The results are, in a certain sense, pretty comical.

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 15, 2023 9:58 UTC (Thu) by rgb (subscriber, #57129) [Link] (6 responses)

I always thought of the Postgres documentation as rather excellent. I am not doubting that there are issues. The fact that they are noticing and discussing them is also a good thing in my book.

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 15, 2023 14:56 UTC (Thu) by dkg (subscriber, #55359) [Link] (1 responses)

I'm inclined to agree with rgb here. Postgres documentation is both comprehensive and well-indexed. And, the psql client itself provides useful embedded/contextual guidance within its REPL (read-eval-print-loop) by way of backslash commands (e.g. \h for SQL and \? for psql itself). I'm pleased to hear that the project is looking at how to improve its documentation further, as it's something that's always possible to improve. I wish more projects had the same commitment to documentation that Postgres has.

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 15, 2023 15:28 UTC (Thu) by brunowolff (guest, #71160) [Link]

I really like Postgres documentation and have learned a lot from it over the years (going back to 7.1). I even use it first when I'm using Oracle at work, because I find it easier to use Postgres documentation and for standard stuff Oracle mostly uses the same syntax and semantics.

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 15, 2023 16:14 UTC (Thu) by Wol (subscriber, #4433) [Link] (2 responses)

My big problem with much documentation is, as I put it, you need to know it before you can make sense of it. It's a very good aide-memoire, but if you don't know what you're doing it's useless.

It's the teaching materials that are so often lacking, and while I don't like "monkey see monkey do" documentation, a cook-book of "this is how to achieve this task, and this is why it works" is both very useful and, sadly, usually lacking.

Which enhances network effects because, without a mentor, how do you learn :-(

Cheers,
Wol

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 16, 2023 11:53 UTC (Fri) by ballombe (subscriber, #9523) [Link] (1 responses)

Agreed. Documentations using system like doxygen is generally 100% accurate and at the same time oten fails to explain how the API is supposed to be used, which is often more important than to know precisely what the individual steps do.

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 18, 2023 16:02 UTC (Sun) by JoelSherrill (guest, #43881) [Link]

I recall that long ago IBM documentation used to include a Theory of Operation section which told you how to use a set of APIs together to accomplish what we would now call a use case. I'm from RTEMS and each "manager" has a Background, Operations, and Directives section in its chapter. The Background is for theory and definitions. The Operations tries to explain how one would use the various services. And the Directives section is man pages. This is an example for our support for Rate Monotonic Scheduling which has some theory a user would be well served to understand (https://docs.rtems.org/branches/master/c-user/rate-monoto...).

We have a git repository of examples but we all think we could use more. I teach a week long class on real-time programming with RTEMS and I've started to include a couple of easy to understand system design cases that (I think) are best solved with a combination of services from 1+ managers.

It is a hard thing mentally to jump from reading man pages to using a set of them to accomplish something productive. And in the FLOSS world, people who write code almost always write the documentation (if they do it at all). And that can be a problem.

One thing I tell people is that you are only a new user once. Please report your experience and issues. People who write the documentation generally don't need to read it.

My USD .02. :)

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 19, 2023 7:24 UTC (Mon) by atnot (subscriber, #124910) [Link]

I think this really comes down to the type of documentation available. Making developers document their work seems to work very well for reference documentation, i.e. dry factual descriptions of the interfaces in a human-readable form.
What it appears less good at creating is other types of documentation, such as tutorials, conceptual overviews and glossaries.

In my opinion, that's still a huge success though. Because reference documentation is really the backbone that the other types of documentation are built on.

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 15, 2023 10:08 UTC (Thu) by rgb (subscriber, #57129) [Link] (3 responses)

This could also make a nice LWN series. Showcasing how various open source projects deal with documentation. Maybe this could also helps others to adjust their best practices, seeing what works and what doesn't in practice.

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 15, 2023 21:29 UTC (Thu) by n0x0n (guest, #165605) [Link] (2 responses)

I like that idea, I feel quite some projects could profit from methodical documentation …

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 16, 2023 1:06 UTC (Fri) by smitty_one_each (subscriber, #28989) [Link] (1 responses)

Tooling is great, but 80% of the effort [waves hands] has to do with the people and their passion for the project. Maybe talent, too.

Haas: The PostgreSQL Documentation and the Limitations of Community

Posted Jun 17, 2023 14:11 UTC (Sat) by wtarreau (subscriber, #51152) [Link]

Absolutely. We're facing similar challenges with haproxy. We know pretty well that the weakest point is the contributor and that we must do anything to ease their task. Actually we're trying hard to make sure there cannot be an excuse for not adding an entry in the doc when something changes so that it's mandatory as well. It works remarkably well, but the points that were mentioned about pgsql regarding out-of-alphabetical-order, occasionally missing entries, or entries that are difficult to find for a newcomer due to multiple sub-sections taking a lot of space is something we know as well.

I've been in the past in the situation where I had to document some features others added. It was amazingly difficult because you rarely have enough context to give good examples and explanations. But nowadays we make sure that everything is documented, and that tools (and humans) help contributors as much as necessary. I'm even willing to fix typos or grammatical errors before committing the patch, but the description of the purpose and how it works are non-negotiable. And it turns out that nobody complains, everyone finds this perfectly normal. This proves that contributors need to be helped, i.e. we have to minimize their effort to contribute doc. As a hint, I often suggest them to reuse a part of the doc in the commit message if they lack inspiration ;-)