Message-ID: From: "davecramer (@davecramer)" To: "pgjdbc/pgjdbc" Date: Sat, 16 May 2026 19:50:34 +0000 Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases In-Reply-To: References: List-Id: X-GitHub-Author-Login: davecramer X-GitHub-Comment-Id: 4467937242 X-GitHub-Comment-Type: issue_comment X-GitHub-Issue: 4075 X-GitHub-Repo: pgjdbc/pgjdbc X-GitHub-Type: comment X-GitHub-Url: https://github.com/pgjdbc/pgjdbc/pull/4075#issuecomment-4467937242 Content-Type: text/plain; charset=utf-8 I'd like to discuss some goals here 1) we should be making it easy for agents to read. Here are some suggestions from an agent ``` Here are the most impactful additions for agent consumption, roughly ordered by effort vs. payoff: High impact, low effort: 1. Structured metadata in — JSON-LD or OpenGraph tags with version numbers, compatibility ranges, and release dates. Agents often look for machine-readable metadata before parsing prose. 2. A llms.txt file at the root — an emerging convention (like robots.txt for AI). It would list the site's purpose, key pages, and preferred citation format. A simple markdown file at /llms.txt pointing to the most useful entry points. 3. An llms-full.txt — a single flat markdown file containing all documentation content concatenated. Lets an agent ingest the entire docs in one fetch instead of crawling dozens of pages. 4. Anchor IDs on every connection property — if the connection properties reference page has #ssl, #loginTimeout, etc., agents can deep-link directly to the relevant property instead of scanning a long table. Medium effort, high value: 5. A machine-readable compatibility matrix — a JSON or YAML file mapping Java versions → PostgreSQL versions → driver versions. Agents frequently need to answer "which version do I use?" and parsing a prose table is error-prone. 6. Code examples with language tags and context comments — e.g., annotating snippets with // Requires: Java 11+, PostgreSQL 14+ so an agent knows applicability without reading surrounding prose. 7. An OpenAPI-style "connection string builder" schema — a JSON Schema describing all connection properties, their types, defaults, and valid ranges. This is the single most useful thing for a coding agent that needs to construct or validate a JDBC URL. Nice to have: 8. Canonical error message → solution mapping in a structured format (JSON/YAML). Agents diagnosing errors could match a stack trace directly to a troubleshooting page without fuzzy-searching headings. 9. Semantic HTML — using , 
,  with proper 
 headers rather than styled divs. Most agents already
  handle this site fine, but semantic markup removes ambiguity.

  The biggest bang for the buck is probably llms.txt + llms-full.txt + a JSON compatibility matrix. Those three files
  would make the site trivially consumable by any AI agent in a single request.
```