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
2026-09-04 15:54:48 +07:00
parent 78a1a905d8
commit 2445df8e20
4 changed files with 143 additions and 33 deletions
+3 -2
View File
@@ -13,7 +13,8 @@ pnpm + Turborepo monorepo. Work from the repository root. Package manager: `pnpm
|---|---|---|
| **Product development** | `apps/web/` | Primary app — features, auth, modules |
| **Component / API reference** | `apps/showcase/` | Living demos of `@repo/*` usage — copy patterns, do not ship product here |
| Deep docs | `apps/docs-dev/` | VitePress (`pnpm dev:docs-dev`) |
| **User documentation** | `apps/docs-dev/` | VitePress user guides (`pnpm dev:docs-dev`) — features and usage only; do not add developer architecture pages |
| **Technical documentation** | sibling `trackgo-be/docs/` | MkDocs / TechDocs — stack, architecture, how to run (web, landing, mobile, backend) |
| Shared UI / forms / foundations | `packages/ui` → `@repo/ui/*` | |
| HTTP, data services, telemetry | `packages/core-api` → `@repo/core-api/*` | |
| Storage | `packages/core-storage` → `@repo/core-storage` | |
@@ -28,7 +29,7 @@ pnpm + Turborepo monorepo. Work from the repository root. Package manager: `pnpm
## Hard rules
- Implement product features in `apps/web`, not in `showcase` or `docs-dev`.
- Before inventing UI or package usage, match `apps/showcase` demos and `apps/docs-dev` docs.
- Before inventing UI or package usage, match `apps/showcase` demos (component/API shape). User workflows: `apps/docs-dev`. Technical FE architecture: sibling `trackgo-be/docs/`.
- Prefer `@repo/ui`, `@repo/core-*`, `@repo/utils` over app-local duplicates or raw Mantine/axios.
- Env files live **inside the app** (`apps/web/.env*`), never at monorepo root. Read env via `src/core/environment` (`ENV`), not `import.meta.env` in components.
- Run scripts from root: `pnpm dev:web`, `pnpm dev:showcase`, `pnpm lint`, `pnpm typecheck:web`, `pnpm test`, `pnpm test:e2e:web`, `pnpm check:all`.