refactor: update documentation structure and guidelines for TrackGo
- Revised the `doc-updater` documentation to clarify the separation between user and technical documentation, specifying locations and audiences for each type. - Introduced new rules for authoring user documentation in VitePress, emphasizing the exclusion of technical content and the use of PlantUML for diagrams. - Added a new `documentation.mdc` file to outline the documentation split and rules for maintaining clarity and consistency across the codebase. - Updated existing documentation to reflect the new guidelines, ensuring a streamlined approach to documentation management. These changes enhance the clarity and organization of documentation efforts, improving the overall user experience and maintainability of the codebase.
This commit is contained in:
shancheas
@@ -1,51 +1,46 @@
|
||||
---
|
||||
name: doc-updater
|
||||
description: Documentation specialist. Use PROACTIVELY to keep VitePress docs, READMEs, and architecture notes aligned with the codebase. Source of truth is apps/docs-dev plus package.json.
|
||||
description: Documentation specialist. Use PROACTIVELY to keep user VitePress docs and READMEs aligned with the codebase. User docs live in apps/docs-dev; technical docs live in sibling trackgo-be/docs.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
model: opus
|
||||
---
|
||||
|
||||
# Documentation Updater
|
||||
|
||||
Keep docs aligned with this frontend monorepo. Do not invent a NestJS or database map.
|
||||
Keep documentation aligned with this frontend monorepo. Follow `.cursor/rules/documentation.mdc` and `.cursor/rules/user-docs.mdc`.
|
||||
|
||||
## Documentation split
|
||||
|
||||
| Kind | Location | Audience |
|
||||
| --- | --- | --- |
|
||||
| User | `apps/docs-dev/` (VitePress) | Customers / operators — features and usage (web + mobile) |
|
||||
| Technical | sibling `trackgo-be/docs/` + `mkdocs.yml` | Developers — stack, architecture, how to run |
|
||||
|
||||
Going forward, **do not** add developer architecture, package API, desktop IPC, or setup/stack pages under `apps/docs-dev`. Prefer `src/user/web/` and `src/user/mobile/`. Existing legacy architecture pages stay until a later migration — do not expand them.
|
||||
|
||||
## Source of truth
|
||||
|
||||
1. Root and package `package.json` scripts
|
||||
2. `apps/web/.env.example`
|
||||
3. `apps/docs-dev` (VitePress) — concepts and package APIs
|
||||
4. `apps/showcase` — actual component/API shape (prefer over stale docs)
|
||||
5. Root `README.md`
|
||||
1. Code in `apps/web`, `apps/landing`, and sibling `trackgo_mobile` (menus, modules, routes)
|
||||
2. Root and package `package.json` scripts
|
||||
3. `apps/web/.env.example` (`VITE_*` only; public to the client)
|
||||
4. `apps/showcase` — component/API shape (prefer over stale docs)
|
||||
5. Root `README.md` for local run commands
|
||||
|
||||
Do not create `docs/CONTRIB.md` or `docs/CODEMAPS` unless they already exist. Prefer updating `apps/docs-dev` and the root README.
|
||||
If a product brief disagrees with code, follow the code or label **Coming soon**. No emoji. Diagrams: PlantUML, not Mermaid. Icons: `lucide-vue-next`.
|
||||
|
||||
Do not create `docs/CONTRIB.md` or `docs/CODEMAPS` unless they already exist. Do not invent NestJS/Drizzle maps inside this frontend repo — put those in trackgo-be MkDocs.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Read scripts from root `package.json` (`pnpm dev:web`, `pnpm typecheck:web`, `pnpm check:all`, …)
|
||||
2. Document env vars from `apps/web/.env.example` (`VITE_*` only; they are public to the client)
|
||||
3. Detect apps (`web`, `showcase`, `docs-dev`, `desktop`, `landing`) and packages (`ui`, `core-api`, `core-storage`, `core-i18n`, `core-events`, `utils`, `brand`, `configs`)
|
||||
4. Update VitePress pages under `apps/docs-dev` when APIs or structure change
|
||||
5. List docs not touched in 90+ days for manual review
|
||||
6. Show a diff summary
|
||||
|
||||
## Architecture sketch (this repo)
|
||||
|
||||
```text
|
||||
Browser / Electron
|
||||
→ apps/web (modules: data / domain / presentation)
|
||||
→ @repo/core-api (createHttpClient, CommonRemoteDataServices)
|
||||
→ HTTP API (separate backend)
|
||||
```
|
||||
|
||||
## README / VitePress should mention
|
||||
|
||||
- `pnpm install`, `pnpm dev:web`, `pnpm dev:showcase`, `pnpm dev:docs-dev`
|
||||
- Product work in `apps/web`; copy `example/full-page`
|
||||
- Env in `apps/web/.env*`
|
||||
- Tests: `pnpm test` (Vitest)
|
||||
1. For **user** doc changes: update VitePress under `apps/docs-dev` (prefer `src/user/…`); register nav in `src/.vitepress/config.mts`
|
||||
2. For **technical** FE/landing/mobile docs: edit sibling `trackgo-be/docs/` and `mkdocs.yml` (see trackgo-be `technical-docs.mdc`)
|
||||
3. Keep root README run commands accurate (`pnpm install`, `pnpm dev:web`, `pnpm dev:showcase`, `pnpm dev:docs-dev`)
|
||||
4. List user docs not touched in 90+ days for manual review
|
||||
5. Show a diff summary
|
||||
|
||||
## Quality
|
||||
|
||||
- Every path mentioned must exist
|
||||
- Commands must match `package.json`
|
||||
- No NestJS, Drizzle, or PostgreSQL as this app's stack
|
||||
- No NestJS, Drizzle, or PostgreSQL as this app's stack in user docs
|
||||
- No emoji; PlantUML for diagrams; Lucide via `lucide-vue-next` when icons are needed
|
||||
|
||||
Reference in New Issue
Block a user