Repository navigation
docs(v2): Guides cleanup (1/3) - #309
Merged
Merged
Conversation
Rewrite the V2 docs for low cognitive load and correct statements that disagree with the API on main. - Cut pitch, metaphors, repeated summaries, and diagrams that restated lists. Decision tables become bullets; field, status, and error reference tables stay. - Restore product content an earlier draft dropped: the context graph, benchmark numbers, isolation guarantee, connectors, use cases. - API reference landing page lists every endpoint group, including Connectors, Webhooks, Feedback, Subgraph, and Delete Collection. - Fix verified inaccuracies: per-file metadata lives in document_metadata items; memory item metadata is an object; query_apps defaults to true; recency_bias defaults to 0.4; max_results caps at 250; operator and/phrase require query_by text; graph_context false only applies in fast mode; type all reads one scope; envelope exceptions; real error codes. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Shorten V2 pages without dropping facts: merge repeated sections, collapse common-mistakes tables that restated warnings, and replace restatements of other pages with links. Prose is about 23% shorter in the guides and 26% in the cookbooks than on main. Also aligns pages with the API on main: 415 is only for bodies that are neither form nor JSON, dense and sparse metadata lanes are declared at database creation, document_metadata items do not take a title, and the SDK page names its envelope exceptions. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
✅ Mintlify HygieneNo issues found. |
OpenHack SummarySecurity review of docs(v2): Guides cleanup (1/3). 37 changed files; 0 findings at or above the low reporting threshold.
Confidence Score: 5/5No reportable security findings were detected in this scan. Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage. Files Needing Attention: None Important Files Changed
Last reviewed commit: bf0bc95 · View review on OpenHack
|
![openhack-agent[bot]](https://avatars.githubusercontent.com/in/2637932?s=60&v=4){kind=small}
Contributor
 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
- Internal search cookbook: search() and explain_decision() now fan out across the four source collections unless one is named, so the cross-source flow reads the content it ingested. TypeScript samples use the SDK's camelCase response fields. - Financial analyst cookbook: earnings and board-memo uploads put per-file metadata in document_metadata instead of an extra app_knowledge item. Filter fields go in metadata; labels and event_time go in additional_metadata, which recency ranking reads. Chunks sort by event_time, not upload time. - Webhooks: signing can be enabled at registration with generate_signing_secret or signing_secret, or later on the signing-secret endpoint. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
/query rejects a listed collection that does not exist, and a collection is created on its first write. The internal search cookbook now asks HydraDB which source collections exist (GET /databases/collections) and searches only those, so a reader who wires up one source can search right away. Applies to search() and explain_decision() in Python and TypeScript. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
The provenance modules import source_collections from the qa module, which ran its example query at import time. Guard the examples in qa and provenance (Python and TypeScript) so they run only when the file is executed directly. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Drop documentation for options the API on main does not act on: - enable_match / filterable: the v2 filter path never reads the flag, and no query matches on user metadata fields with it. Removed from guidance, schema field tables, and code samples. A schema field needs only name and data_type; filters match declared metadata fields as before. - Memory item relations: memories[] items have no relations field (the value is never read), so the "Connect related memories" section, field rows, and sample keys are gone. relations on document_metadata and app_knowledge items still work and stay documented. - Memory item expiry_time: no such field exists; rows removed. Also drops the stale claim that schema updates create MongoDB filter indexes, and words vector sync in terms of embedding flags. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
pathToFileURL throws when process.argv[1] is undefined (REPL or node -e), which would make the qa and provenance modules fail to import. Check the argument first. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Review found the rewrite flattened the docs: it cut voice, examples, tables, diagrams, and context. Every V2 page now starts again from its original text on main, with only these changes on top: - Verified factual corrections (defaults, limits, error codes, field shapes, envelope and scoping rules, endpoint behavior). - Code sample bug fixes, including the reviewed cookbook fixes. - Removals requested in review: enable_match/filterable, memory-item relations and expiry_time. - Missing facts added in the original format (for example the endpoint inventory rows for Connectors, Webhooks, Feedback, Subgraph). - Broken links, anchors, and diagram syntax. - Punctuation only: dashes and arrows in prose replaced, bold labels end with a colon, typos fixed. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
SohamRatnaparkhi
changed the title
Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
SohamRatnaparkhi
changed the title
This was referenced Oct 5, 2026
SohamRatnaparkhi
force-pushed
the
t3code/rewrite-docs-declutter
branch
from
October 9, 2026 09:02
133f19c to
1154e92
Compare
Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Contributor
Author
|
Please reassess the remaining findings against 32cce60:
Mintlify build validation and hygiene pass. All legacy Ecosystem headings were compared with main, and each retained package link is outside the contribution footer. |
Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
…ides Introduction: drop the retrieval section, bring back a short "problem" and "principle", link every benchmark to its dataset, say HydraDB is serverless. Quickstart: plainer title and steps, Copy-only prompt, no meta commentary, model-prompt section folded into one sentence. Core Concepts: no support-assistant framing, inferred traits, query as a multi-stage pipeline, metadata as the WHERE clause. Dashboard links point at dashboard.hydradb.com. A proofreading pass over every Guides page fixes agreement, articles, comma splices, repeated sentences, meta lead-ins, spaced hyphens used as dashes, and a few contradictions between pages. Refs PRO-2457 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Remove meta commentary, repeated sentences, hand-holding, and routine callouts; split run-on sentences; keep every fact, table, and code block. Align collection advice with the company-brain guidance on the Architecture, Connectors, and Multi-tenancy pages, and settle the Gmail account-scope contradiction on Connectors. Refs PRO-2457 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
…eclutter Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
✅ OpenHack SummarySecurity review of docs(v2): Guides cleanup (1/3). 37 changed files; 0 findings at or above the low reporting threshold.
Confidence Score: 5/5No reportable security findings were detected in this scan. Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage. Files Needing Attention: None Important Files Changed
Last reviewed commit: f5297ec · View review on OpenHack
|
Quickstart: write the database step for a reader with nothing set up, link API Results plainly, drop the closing "builds on this loop" line. Knowledge: name connectors as the third way to add knowledge, move the ACL mention out of the opening, fix the outline and App Sources link. Architecture: context moves from ingestion to search; the search row lists only POST /query. Memories persist across future sessions. Across the Guides, say "context" for what users store and search, replace "X shows the full..." links with "See X", and rewrite outline items that read as fragments. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Keep access control out of the Knowledge opening, and say in the Retrieve knowledge section that documents with an acl need the caller's identity on every query; metadata filters do not replace it. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
SohamRatnaparkhi
added a commit
that referenced
this pull request
Oct 22, 2026
* docs(v2): isolate API reference and response fixes for PRO-2457 Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): line-by-line pass over the API Reference pages Read every API Reference page and api-results line by line, keeping the original voice and cutting only repetition and wrong claims: - Query: drop the alias Note and the Default Behaviors block that restated the field table; split the indexing and collection-scope advice; link Recommended configurations by name. - Query overview: new description, removed the duplicate Tip, and the personalized recipe now says to list both collections when shared docs live elsewhere. Thinking mode always includes graph context. - Submit Feedback: removed a Note that repeated the field rules. - Error Responses: removed the E6001 Note that repeated the table, and the troubleshooting bullet no longer names the deprecated tenant_metadata. - Labels end with colons throughout. Connector and webhook pages were read and left as they are. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): align API examples and specification with behavior Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): correct generated response and metadata schema examples Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): model nullable fetch errors in the API schema Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): allow null fetch fields in content and URL modes Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): explain API results before advanced graph fields Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): put the four core calls first in the API reference Most integrations are create database, ingest, check status, query. The sidebar now opens with a "Start here" group holding exactly those four endpoints and the overview, and the overview page leads with the same four calls before the endpoint groups and the full inventory. The resource groups still list every endpoint, so browsing by resource works as before. SDKs and Error Responses move to a Reference group. Refs PRO-2457 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): link BYOG references to the merged page's non-Cypher section The two Bring Your Own Graph pages are being merged into one (PR #304, carried into #309), so the ingest and query references point at the section that covers graph_payload. Refs PRO-2457 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): add a Webhooks overview and link connector instructions to Connectors - Webhooks: Overview, first in the Webhooks group, lists every webhook endpoint including the signing-secret calls, the typical sequence, and how deliveries are signed and retried (exponential backoff, 16 attempts or 48 hours on Cloud, per domain/webhooks/retry.go). - The connector API pages link to the custom instructions section of the Connectors guide, where that content now lives. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): apply the review principles across the API reference - Code tabs: every connector and webhook endpoint now shows Python SDK, TypeScript SDK, and cURL, like the rest of the reference. Update Metadata Schema, Update Source Metadata, and an Ingest Context example used raw HTTP in their SDK tabs; they now call the SDK. Every new SDK call was run against a local mock server and type-checked against SDK 2.1.7, and sends the same request as its cURL. - Callouts: 40 routine Note, Info, Tip, and Warning boxes become plain text. Warnings remain only where data or access is at risk: replacing a connector resource, deleting a database, deleting a source that is still indexing, and an acl_warning on a connector resource. - Overview: drops the core concepts table, the endpoint groups table, the SDK setup code, and the status code table, each covered on its own page; the endpoint inventory is grouped by resource, each group linking to its overview. 2,202 words to 1,655. - Query: the tuning list that repeated the Query guide becomes a link; Behavior notes becomes Common mistakes. - Error Responses: notes that both SDKs already retry 408, 429, and 5xx twice with exponential backoff (Python also 409), and how to raise it. - Wording: no "material", no per-user or one-user framing of collections and memories; connector examples write to one company_docs collection; no arrows in prose. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): carry Guides clarity and working examples into API reference Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): keep signing endpoints in the webhook table Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): fix feedback failures, SDK casing, and reference links Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): align API examples and response guidance with current contracts Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): report incomplete relation pagination Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): separate core endpoint shortcuts from API corrections Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): organize API results by response format Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): restore supported enable_match schema field Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): remove repeated API result examples and guidance Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): fix provider authentication and remove unsupported CLI example Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): clarify query input and result limits Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): scope connector queries to the configured collection Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): shorten endpoint guidance and link shared metadata docs Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): remove borders from section anchors Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): document current metadata filters and model context Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): simplify the public API contract and reference (PRO-2457) Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): align the final subgraph description (PRO-2457) Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): align nullable fields with generated SDKs (PRO-2457) Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): retain authentication and contract constraints (PRO-2457) Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): keep subgraph corpus wording consistent (PRO-2457) Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> * docs(v2): retain combined list and delete selectors (PRO-2457) Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> --------- Signed-off-by: SohamRatnaparkhi <soham@hydradb.com> Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The V2 Guides assumed internal terminology, repeated concepts, and included examples that did not match the API or SDK. This change puts setup and concrete requests first, explains fields where they are used, and keeps detailed code in accordions.
The October 12 review checked every original changed file. It fixed ingestion/query timing, TypeScript response-union handling, dropped agent-reference filters, permission wording, BYOG deletion and write retries, benchmark destinations, and plugin setup gaps. Two V1 link-only edits were removed from scope. The three API-reference files only update links to the merged connector-instructions section. API Results and the rest of the API work remain in #310; cookbooks remain in #311.
Validation: Mintlify build, hygiene, internal links, 61 Python/106 Bash/77 JSON syntax checks, and 54 TypeScript excerpt checks against SDK 2.1.7. Executed 34 TypeScript and 26 Python SDK examples with mocked HTTP, including the full Quickstart and metadata, ACL, connector, and webhook flows. No production data was created or changed; benchmark runs were not repeated.