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:
@@ -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