shancheas
2445df8e20
- 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.
90 lines
2.3 KiB
Plaintext
90 lines
2.3 KiB
Plaintext
---
|
|
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
|
|
```
|