Analysis: PATCH to Add Introductory Paragraph to Getting Started Chapter
Core Problem
This is a documentation-only patch proposing to add a brief introductory paragraph to the "Getting Started" chapter of the PostgreSQL tutorial documentation. The stated goal is to provide new users with a narrative overview of the chapter's contents before they dive into the subsections.
Technical Context
The PostgreSQL documentation is structured using DocBook/SGML and rendered into HTML. The "Getting Started" chapter (located at doc/src/sgml/start.sgml or equivalent) already contains a table of contents that is auto-generated from its section headings. The rendered page at https://www.postgresql.org/docs/current/tutorial-start.html displays this TOC prominently at the top of the chapter.
Proposed Solution
The patch adds a short paragraph summarizing the topics covered in the chapter — essentially a prose restatement of what the table of contents already communicates structurally.
Key Disagreement and Resolution
Bruce Momjian — a long-time PostgreSQL committer and documentation maintainer — rejected the patch on the grounds that it simply duplicates information already present in the auto-generated table of contents that appears directly above where the proposed text would be inserted. His argument is one of documentation economy: redundant text adds maintenance burden without providing additional value to readers.
This is a common pattern in PostgreSQL documentation reviews. The project maintains a high bar for documentation changes, requiring that additions provide clear informational value beyond what existing structural elements (TOCs, cross-references, section titles) already convey. Purely cosmetic or stylistic additions that restate existing information are typically rejected.
Assessment
The patch is unlikely to be committed. While the contributor's intent — making the documentation more approachable for newcomers — is valid, the specific implementation (a paragraph that restates the TOC) doesn't meet the project's standards for documentation contributions. A more compelling approach might have been to add context that the TOC cannot provide: explaining prerequisites, suggesting a reading order for users with different backgrounds, or describing what the reader will be able to accomplish after completing the chapter.
Broader Implications
This thread illustrates the PostgreSQL community's approach to documentation patches:
- Even "simple" doc patches receive substantive review
- Redundancy is actively avoided in the documentation
- New contributors should examine how rendered documentation already presents information before proposing additions