Skip to content

docs: remove maintainer-only content, duplicates and unbacked claims - #104

Merged
kannandreams merged 2 commits into
mainfrom
docs/maintainer-content-cleanup
Aug 29, 2026
Merged

docs: remove maintainer-only content, duplicates and unbacked claims#104
kannandreams merged 2 commits into
mainfrom
docs/maintainer-content-cleanup

Conversation

@kannandreams

Copy link
Copy Markdown
Collaborator

A review of everything user-facing in the repository, with three goals: remove content that only the maintainer needs, remove filler, and remove claims that the code does not back.

Removed from the repository

  • capabilities/agent-forge/ (37 files) — a vendored AI-agent skill library. Maintainer tooling; it lives in its own repository.
  • ROADMAP.md, TASKS.md, SPEC.md, DECISIONS.md — internal planning scaffolds. TASKS.md and SPEC.md had unclosed code fences; ROADMAP.md proposed glyf serve as future work. The two ADRs in DECISIONS.md now live in ARCHITECTURE.md.
  • docs/ — an older, diverged copy of the docs-site guides. The README table now links the docs-site sources on GitHub, so the guides stay reachable before the site opens. Four sentences that existed only in docs/ were carried across.
  • docs/release.md and the rulesets how-to — maintainer procedure, relocated out of the public repo.
  • The three blog posts — each was a few sentences of the same thesis with no commands or output; the blog is unlinked until there is a post with content.
  • examples/screenshots.md — an asset-capture checklist.

Claims corrected

  • toolbar.actions was documented with a "show only one action" example. The loader validates the key but toolbar.j2 never reads it, so the example did nothing. Removed from the docs and from the example dashboards. (The key is still accepted, so existing YAML keeps working — worth a follow-up to either wire it or drop it.)
  • npm install @glyf/client @glyf/react and the GlyfProvider example — these packages do not exist. The page now documents the real bundle.json contract and points the JavaScript packages at the roadmap.
  • activation_health(0.82) in the product-analytics page raises TypeError (the macro's parameters are keyword-only). The page now shows the shipped product.yml.
  • Roadmap listed serve, interactive charts and the Looker guide as planned; all three ship.
  • CONTRIBUTING.md promised "an active discussion thread every month"; there has been one welcome thread since May.
  • ARCHITECTURE.md described theme files and a token JSON that do not exist.

Consolidated

  • guides/configurationreference/configuration (one page, now also documenting execution.backend and that render.formats accepts only svg/png).
  • get-started/existing-dbt-projectget-started/quickstart (70% identical).
  • Three AI-context pages → one, stating the validation commands once instead of four times.
  • The macro chapter was in both the dashboard YAML and macros guides; the YAML guide now points at the macros guide, which also un-nests "Custom macros" from under "Theme".
  • llms.txt rewritten: its "core workflow" omitted glyf build and glyf serve.

Checks

  • npm run build in docs-site/ passes with onBrokenLinks: 'throw'.
  • uv run pytest: 115 passed.

Delete capabilities/agent-forge (a vendored AI-agent skill library used only
by the maintainer), ROADMAP.md, TASKS.md, SPEC.md and DECISIONS.md (internal
planning scaffolds, two of them with unclosed code fences), and the root docs/
directory, which was an older copy of the docs-site guides that the README
still linked to. The release runbook and the rulesets how-to move to the
maintainer handbook.

AGENTS.md is now self-contained, ARCHITECTURE.md describes only files that
exist and absorbs the two ADRs, CONTRIBUTING.md no longer promises a monthly
discussion thread that never happened, and CHANGELOG.md carries the 0.3.0
release date. The README documentation table points at the docs-site sources
so it works before the site opens.
- Drop the screenshots checklist, the empty Slack section, the Looker
  'questions to resolve' and the three placeholder blog posts; the blog is
  unlinked until there is a post with content.
- Rewrite the roadmap: serve, interactive charts and the Looker guide had
  already shipped; three items were internal chores.
- Stop documenting toolbar.actions: the loader validates it but the template
  never reads it, so the 'show only one action' example did nothing. The
  example dashboards drop the key too.
- Embedded analytics now documents only the bundle.json contract; the
  @glyf/client and @glyf/react packages do not exist yet.
- Product analytics shows the real dashboards/product.yml; the previous copy
  called activation_health(0.82), which raises against the macro's
  keyword-only signature.
- Merge guides/configuration into the reference page (adding the undocumented
  execution.backend key and the svg/png-only rule), fold existing-dbt-project
  into the quickstart it duplicated, and collapse the three AI-context pages
  into one.
- Cut the macro chapter duplicated between the dashboard YAML and macros
  guides, which also un-nests 'Custom macros' from under 'Theme'.
- Rewrite llms.txt around glyf build / glyf serve and the current page set.
- Carry over three sentences from the deleted root docs tree.
@kannandreams
kannandreams merged commit 08e09ef into main Aug 29, 2026
5 checks passed
@kannandreams
kannandreams deleted the docs/maintainer-content-cleanup branch August 29, 2026 22:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant