Skip to content

docs: Fix 24 documentation audit findings#47

Merged
JoshDoesIT merged 1 commit into
mainfrom
docs/documentation-audit-fixes
Mar 8, 2026
Merged

docs: Fix 24 documentation audit findings#47
JoshDoesIT merged 1 commit into
mainfrom
docs/documentation-audit-fixes

Conversation

@JoshDoesIT
Copy link
Copy Markdown
Owner

@JoshDoesIT JoshDoesIT commented Mar 8, 2026

Summary

Comprehensive documentation audit identified and fixed 24 findings: 7 inaccuracies, 4 inconsistencies, and 13 improvement opportunities across all project docs.

The most impactful fix: setup.sh pulled llama3 but the CLI defaulted to qwen2.5:14b, causing errors on first run for any new contributor following the docs.

Changes

  • setup.sh: Default model llama3qwen2.5:14b to match _defaults.py
  • README.md: Add html to output formats, fix tree structure, add mypy badge, document default model + resource requirements, add missing make targets
  • ARCHITECTURE.md: Expand enrichment.py description, add eval_command, eval_ragas, _json_utils to supporting modules table, refine strict mode claim
  • CONTRIBUTING.md: Add uv prerequisite, fix model reference, add make typecheck/check/test-all/docs, add 3 missing eval test suites, fix eval fixture schema fields
  • CHANGELOG.md: Fix inaccurate "dynamic version" claim, add 6 missing features to Unreleased
  • SECURITY.md: Add LLM prompt injection to scope
  • CODE_OF_CONDUCT.md: Add specific contact info replacing vague "contact information available on the repository"
  • mkdocs.yml: Add pymdownx.snippets extension (fixes broken docs/architecture.md), add eval API reference to nav
  • docs/index.md: Add eval module to API reference list
  • docs/api/eval.md: New mkdocstrings page for eval_command
  • .github/SUPPORT.md: Note that Discussions requires repo enablement

Test Plan

  • All existing tests pass (uv run pytest)
  • New tests written following TDD (Red → Green → Refactor)
  • Linting passes (uv run ruff check .)
  • Type checking passes (uv run mypy src/)

Documentation-only changes — no production code modified, no new tests needed.

Checklist

  • Tests written before implementation (TDD)
  • Documentation updated (if applicable)
  • No unused code, console logs, or dead comments
  • Follows existing project coding style

Correct inaccuracies, fill gaps, and improve documentation quality
across all project docs.

Key fixes:
- Align setup.sh model with runtime default (qwen2.5:14b)
- Add missing html output format to README
- Fix broken mkdocs architecture page (add pymdownx.snippets)
- Add eval module to ARCHITECTURE.md and mkdocs nav
- Add uv prerequisite and missing make targets to CONTRIBUTING.md
- Add LLM prompt injection to SECURITY.md scope
- Fix dynamic version claim and add missing features to CHANGELOG.md
- Add specific contact info to CODE_OF_CONDUCT.md
- Add mypy strict badge to README
@JoshDoesIT JoshDoesIT merged commit 5c22447 into main Mar 8, 2026
5 checks passed
@JoshDoesIT JoshDoesIT deleted the docs/documentation-audit-fixes branch March 8, 2026 20:11
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