docs: condense the site and cut its duplicated pages - #249
Merged
Merged
Conversation
The site had grown three habits that made it hard to read: the same content written twice on neighbouring pages, reference material delivered as essay paragraphs, and hand-maintained nav footers the theme already renders. - `preset-engine` and `redis-backed-engine` each carried a Quick Start, an API Reference block, and a preset table. They now split by question: which preset to pick, versus how the engine stays in sync across instances. - `reference/api` repeated Create/Add/Find/Info/Flush/Close in a second "Redis-Backed Engine with Presets" section, and gave a one-line H3 to each method. Methods are tables now; the prose is spent on the contracts that need it (FindMatches, FindStream, parallel boundaries). - Removed the `## Navigation` footers from eight pages. The layout renders breadcrumbs, top nav, and a per-page TOC, and only some pages carried them. - `monitoring` listed the same four Grafana panels twice; `deployment` repeated the topology snippets from Quick Start and the health wiring from server/running. Three defects surfaced while rewriting: - `extending/custom-storage` linked to `guides/presets/`, which does not exist - `cli/_index` said twenty commands, `getting-started/installation` said nineteen; both counts are gone, the command table is the source - `reference/api` omitted `FindSetContext` from its context-variants list, though `api/v1.txt` carries it The README's "Large versioned dictionaries" section had been appended below License; it is a top-level section now. Performance and verification reports keep every data table unchanged — only their surrounding prose is shorter. No documented behavior changed. 166 KB to 131 KB across 32 files. `make docs-verify` compiles all 21 Go blocks, `hugo` builds clean, and all 31 pages' internal links resolve.
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
1 participant
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.
Pull Request
Description
The docs site had grown three habits that made it hard to read: the same content written twice on neighbouring pages, reference material delivered as essay paragraphs, and hand-maintained nav footers the theme already renders. This rewrites all 31 site pages plus the README for concision, with no change to what any of them documents.
Deduplication
guides/preset-engineandguides/redis-backed-engineeach carried a Quick Start, an API Reference block, and a preset table. They now split by question: which preset to pick versus how the engine stays in sync across instances. Both URLs are preserved.reference/apirepeated Create/Add/Find/Info/Flush/Close in a second "Redis-Backed Engine with Presets" section and gave a one-line H3 to each method. Methods are tables now; the prose is spent on contracts that need it (FindMatches,FindStream, parallel boundaries).operations/monitoringlisted the same four Grafana panels twice;operations/deploymentrepeated the topology snippets from Quick Start and the health wiring fromserver/running.Structure
## Navigationfooters from eight pages — the layout already renders breadcrumbs, top nav, and a per-page TOC, and only some pages carried them.Defects found while rewriting
extending/custom-storagelinked toguides/presets/, which does not exist →guides/preset-engine/cli/_indexsaid twenty commands,getting-started/installationsaid nineteen (leftover from docs: resync the site with the code it describes #245). Both counts are gone; the command table is the source, so it cannot drift again.reference/apiomittedFindSetContextfrom its context-variants list, thoughapi/v1.txtcarries itPerformance and verification reports (
benchmarks,versioned-performance,r2-r3-performance) keep every data table byte-for-byte — only their surrounding prose is shorter.166 KB to 131 KB (-21%) across 32 files.
Type of Change
Checklist
make test) — no Go files changed; pre-commit skipped the Go hooksmake vet— samemake lint) — samemake build) — samechangie new)Additional Notes
Verification run against this branch:
make docs-verify— all 21<!-- doccheck -->blocks compilehugo— site builds cleanapi/v1.txt(ErrRedisClusterDB,ErrSuggestRequiresRedis,FindSet,FindSetContext,DefaultParallelOptions)No documented behavior changed, so the
v1promise inreference/compatibilityis unaffected — that page's own rule is that wording is not covered, only what it describes.By submitting this PR, I agree that my contributions will be licensed under the Apache License 2.0.