I was looking at the documentation index this morning[1], and I can't help feeling like there are some parts of it that are over-emphasized and some parts that are under-emphasized. I'm not sure what we can do about this exactly, but I thought it worth writing an email and seeing what other people think.
The two sections of the documentation that seem really under-emphasized to me are the GUC documentation and the SQL reference. The GUC documentation is all buried under "20. Server Configuration" and the SQL command reference is under "I. SQL commands". For reasons that I don't understand, all chapters except for those in "VI. Reference" are numbered, but the chapters in that section have Roman numerals instead. I don't know what other people's experience is, but for me, wanting to know what a command does or what a setting does is extremely common. Therefore, I think these chapters are disproportionately important and should be emphasized more. In the case of the GUC reference, one idea I have is to split up "III. Server Administration". My proposal is that we divide it into three sections. The first would be called "III. Server Installation" and would cover chapters 16 (installation from binaries) through 19 (server setup and operation). The second would be called "IV. Server Configuration" -- so every section that's currently a subsection of "server configuration" would become a top-level chapter. The third division would be "V. Server Administration," and would cover the current chapters 21-33. This is probably far from perfect, but it seems like a relatively simple change and better than what we have now. I don't know what to do about "I. SQL commands". It's obviously impractical to promote that to a top-level section, because it's got a zillion sub-pages which I don't think we want in the top-level documentation index. But having it as one of several unnumbered chapters interposed between 51 and 52 doesn't seem great either. The stuff that I think is over-emphasized is as follows: (a) chapters 1-3, the tutorial; (b) chapters 4-6, which are essentially a continuation of the tutorial, and not at all similar to chapters 8-11 which are chalk-full of detailed technical information; (c) chapters 43-46, one per procedural language; perhaps these could just be demoted to sub-sections of chapter 42 on procedural languages; (d) chapters 47 (server programming interface), 50 (replication progress tracking), and 51 (archive modules), all of which are important to document but none of which seem important enough to put them in the top-level documentation index; and (e) large parts of section "VII. Internals," which again contain tons of stuff of very marginal interest. The first ~4 chapters of the internals section seem like they might be mainstream enough to justify the level of prominence that we give them, but the rest has got to be of interest to a tiny minority of readers. I think it might be possible to consolidate the internals section by grouping a bunch of existing entries together by category. Basically, after the first few chapters, you've got stuff that is of interest to C programmers writing core or extension code; and you've got explainers on things like GEQO and index op-classes and support functions which might be of interest even to non-programmers. I think for example that we don't need separate top-level chapters on writing procedural language handlers, FDWs, tablesample methods, custom scan providers, table access methods, index access methods, and WAL resource managers. Some or all of those could be grouped under a single chapter, perhaps, e.g. Using PostgreSQL Extensibility Interfaces. Thoughts? I realize that this topic is HIGHLY prone to ENDLESS bikeshedding, and it's inevitable that not everybody is going to agree. But I hope we can agree that it's completely silly that it's vastly easier to find the documentation about the backup manifest format than it is to find the documentation on CREATE TABLE or shared_buffers, and if we can agree on that, then perhaps we can agree on some way to make things better. -- Robert Haas EDB: http://www.enterprisedb.com [1] https://www.postgresql.org/docs/16/index.html