Skip to content

chore: Remove unnecessary and stale documentation #425

@manojbajaj95

Description

@manojbajaj95

Summary

Prune redundant, superseded, or internal-only documentation so the repo has a clear, maintainable docs surface.

Current state

Documentation is split across several trees:

Location Purpose
docs/site/ Public Mintlify docs (integrations, guides, reference) — published at authsome.ai/docs
docs/guides/ Repo-local guides (e.g. self-hosting.md)
docs/adr/ Architecture decision records
docs/internal/ Internal design docs (authsome-design.md, cli-design-review.md, manual-testing.md)
docs/refactor.md Historical storage/identity refactor plan — largely shipped
CONTEXT.md, docs/UBIQUITOUS_LANGUAGE.md Domain vocabulary for contributors/agents
AGENTS.md, CONTRIBUTING.md, README.md Contributor and user entry points

Candidates for removal or consolidation

  • docs/refactor.md: Marked as historical; phases 1–8 largely shipped. Content overlaps with CONTEXT.md and ADRs.
  • docs/internal/authsome-design.md: Canonical v1 design doc — may duplicate docs/site/concepts/architecture.mdx and CONTEXT.md.
  • docs/internal/cli-design-review.md, docs/internal/manual-testing.md: Internal-only; evaluate whether still referenced.
  • Overlap between docs/site/ and repo-root guides: e.g. self-hosting exists in docs/guides/ but not clearly linked from site docs.
  • Stale terminology: Some docs may still reference retired concepts (per CONTEXT.md flagged ambiguities).

Proposed work

  • Audit all docs/ files for duplication against docs/site/ and CONTEXT.md.
  • Delete or archive docs that are superseded and unreferenced.
  • Move any still-valuable internal content into ADRs or public docs.
  • Update docs/site/docs.json / navigation if pages are removed or merged.
  • Ensure AGENTS.md and contributor pointers reference only canonical docs.

Do not remove without review

  • docs/adr/* — keep unless explicitly superseded by a newer ADR.
  • CONTEXT.md, docs/UBIQUITOUS_LANGUAGE.md — active agent/contributor context.
  • docs/agents/* — issue tracker and triage conventions.

Acceptance criteria

  • No duplicate canonical explanations of the same concept in conflicting places.
  • Clear rule: public user docs in docs/site/, contributor/domain docs at repo root, ADRs for decisions.
  • Broken links from README, AGENTS.md, and site nav are fixed or removed.

Metadata

Metadata

Assignees

Labels

needs-triageMaintainer needs to evaluate this issue

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions