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
@@ -0,0 +1,25 @@
|
||||
---
|
||||
description: TrackGo docs split — user VitePress in apps/docs-dev, technical MkDocs in trackgo-be
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Documentation Split
|
||||
|
||||
TrackGo has two documentation kinds. Sibling repos: `trackgo-be`, `trackgo-fe`, `trackgo_mobile`.
|
||||
|
||||
| Kind | Audience | Location | Tooling |
|
||||
| --- | --- | --- | --- |
|
||||
| Technical | Developers / engineers | `trackgo-be/docs/` + `trackgo-be/mkdocs.yml` | MkDocs / Backstage TechDocs |
|
||||
| User | Customers / operators | `apps/docs-dev/` (this repo) | VitePress |
|
||||
|
||||
## Rules
|
||||
|
||||
- Technical: stack, architecture, how to run, module interactions (backend, web, landing, mobile) — write in trackgo-be MkDocs, not here.
|
||||
- User: features and usage for web and mobile only — write under `apps/docs-dev`.
|
||||
- Going forward, docs-dev is **user documentation only**. Do not add developer architecture, package APIs, desktop IPC, or setup/stack pages there. Existing legacy pages stay until a later migration.
|
||||
- No emoji in any documentation.
|
||||
- Diagrams and sequence diagrams: PlantUML fenced blocks (` ```plantuml `), not Mermaid.
|
||||
- Icons in user docs: Lucide via `lucide-vue-next` (VitePress is Vue). Match icon names used in `apps/web` (`lucide-react` in `menu.data.ts`). Do not paste ad-hoc SVG copies of Lucide.
|
||||
- Source of truth is the codebase. If a brief disagrees with code, follow the code or label **Coming soon**. Do not invent features.
|
||||
|
||||
Authoring details: `.cursor/rules/user-docs.mdc` (when editing `apps/docs-dev/**`).
|
||||
@@ -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`.
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
description: How to write TrackGo user docs in VitePress (apps/docs-dev)
|
||||
globs: apps/docs-dev/**
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# User Documentation (VitePress)
|
||||
|
||||
Audience: customers and operators. Location: `apps/docs-dev/`.
|
||||
|
||||
## Scope
|
||||
|
||||
Document **features and usage** (menus, screens, workflows) for:
|
||||
|
||||
- Web — `apps/web`
|
||||
- Mobile — sibling `trackgo_mobile`
|
||||
|
||||
Do **not** document tech stack, package internals, Electron IPC, or monorepo setup here. Technical docs belong in `trackgo-be/docs/` (MkDocs).
|
||||
|
||||
## Where to add pages
|
||||
|
||||
Prefer:
|
||||
|
||||
```text
|
||||
apps/docs-dev/src/user/web/
|
||||
apps/docs-dev/src/user/mobile/
|
||||
```
|
||||
|
||||
Register new pages in `src/.vitepress/config.mts` sidebar/nav.
|
||||
|
||||
Do **not** add new pages under the legacy architecture sidebar paths (`/packages/*`, `/apps/desktop/*`, `/setup`, `/overview`). Those stay until a later migration; do not expand them.
|
||||
|
||||
Existing user how-tos (e.g. `src/apps/web/SALES_WORKFLOW.md`): keep user-facing; when editing, convert Mermaid to PlantUML and remove emoji.
|
||||
|
||||
## Topics (only if present in code)
|
||||
|
||||
**Web** (from menus / modules — verify in `apps/web`):
|
||||
|
||||
- Master data: company settings, branches, divisions, customers, products, employees
|
||||
- Users and privileges
|
||||
- Plans (one-time / recurring) and attached invoices / packing slips
|
||||
- Live timeline / activity history
|
||||
- Import of invoices / packing slips
|
||||
- Sales flow: request → order → invoice → payment
|
||||
- Logistics packing slips
|
||||
|
||||
**Mobile** (from `trackgo_mobile/lib/ui/features/` and `lib/config/router.dart`):
|
||||
|
||||
- Branch check-in before work
|
||||
- Plans, customers / visits, invoice payment
|
||||
- Home performance / history
|
||||
|
||||
Anything in a product brief that is not in the code → **Coming soon**.
|
||||
|
||||
## Style
|
||||
|
||||
- No emoji.
|
||||
- Diagrams / sequences: PlantUML only (do not add Mermaid on new or edited pages).
|
||||
- Icons: `lucide-vue-next` in markdown `<script setup>`, same Lucide names as web menus.
|
||||
|
||||
````markdown
|
||||
```plantuml
|
||||
@startuml
|
||||
actor User
|
||||
User -> Web: Create sales order
|
||||
@enduml
|
||||
```
|
||||
````
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { ShoppingCart } from 'lucide-vue-next'
|
||||
</script>
|
||||
```
|
||||
|
||||
```text
|
||||
# BAD — new architecture page in docs-dev
|
||||
apps/docs-dev/src/packages/core-api/new-api.md
|
||||
|
||||
# BAD — Mermaid / emoji / React Lucide in VitePress
|
||||
```mermaid
|
||||
```
|
||||
"📦 Sales"
|
||||
import { ShoppingCart } from 'lucide-react'
|
||||
|
||||
# GOOD
|
||||
apps/docs-dev/src/user/web/sales-workflow.md
|
||||
apps/docs-dev/src/user/mobile/check-in.md
|
||||
```
|
||||
Reference in New Issue
Block a user