Tux Machines

The PostgreSQL Documentation and the Limitations of Community

Posted by Roy Schestowitz on Jun 15, 2023

Open Hardware/Modding: Retro, Raspberry Pi, Arduino, and More

NVIDIA driver 535.54.03 for Linux and AMD GPUs to get Ray Tracing turned on for Mesa 23.2

In my opinion, the PostgreSQL documentation is simultaneously excellent and fairly poor, and both its excellence and its shortcomings are direct results of the process by which the documentation is produced. The PostgreSQL documentation is stored in the same git repository as the source code, and anyone who patches the source code so as to change documented behavior must also patch the documentation to match.

This means that nearly all documentation updates are made by the developer who is most familiar with what is changing in the code, or sometimes by another developer who has studied those changes closely. Therefore, the documentation is usually extremely accurate. Sure, there are oversights, but it would be incredible to discover that some PostgreSQL command has a documented option which doesn't actually exist, or that a parameter which is documented to take a string argument actually takes an integer or a Boolean. Typically, the descriptions of what SQL statements do and how that behavior is changed by parameter settings or options passed to the command itself are crisp and precise.

We're particularly good at tables and lists. Every SQL command that exists is listed in the documentation index, and anybody who adds a new SQL command will add it to the list, and write a documentation page for it that looks just like all of the other ones. Every configuration parameter that exists is listed in the documentation with a description of what it does using semi-standard phraseology. When someone creates a new one, they're bound to add it to the list and describe it using the same phraseology that's already used for the existing parameters. Corrections to this kind of documentation are often on the level of re-alphabetizing things that have fallen out of alphabetical order, or fixing some bit of markup that wasn't done in the same way as all of the other entries. Grown men slink away in shame when it is pointed out to them that the parameter type is listed as bool when it actually should be enum.

Read on

↺ Read on

Also (discussion): Haas: The PostgreSQL Documentation and the Limitations of Community

↺ Haas: The PostgreSQL Documentation and the Limitations of Community

gemini.tuxmachines.org