pgjdbc/pgjdbc GitHub issues and pull requests (mirror)
help / color / mirror / Atom feedFrom: davecramer (@davecramer) <[email protected]>
To: pgjdbc/pgjdbc <[email protected]>
Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases
Date: Sat, 16 May 2026 19:50:34 +0000
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
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 <head> — 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 <code>, <pre>, <table> with proper <th> 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.
```
view thread (64+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: github://pgjdbc/pgjdbc
Cc: [email protected], [email protected]
Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases
In-Reply-To: <<[email protected]>>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox