shancheas
a6a06ae1de
- Created a new `mkdocs.yml` file to define the structure and navigation for technical documentation. - Updated `doc-updater.md` to clarify the role of the documentation specialist and the split between technical and user documentation. - Introduced new rules in `documentation.mdc` and `technical-docs.mdc` to guide the creation of documentation, emphasizing the separation of technical and user content. - Added a `readme.md` in the `docs` directory to provide instructions for using MkDocs with Backstage.
80 lines
1.9 KiB
Plaintext
80 lines
1.9 KiB
Plaintext
---
|
|
description: How to write TrackGo technical docs in MkDocs (docs/ + mkdocs.yml)
|
|
globs: docs/**/*.md,mkdocs.yml
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Technical Documentation (MkDocs)
|
|
|
|
Audience: developers and engineers. Location: `docs/` + `mkdocs.yml`.
|
|
|
|
## Scope
|
|
|
|
Document tech stack, architecture, how to run, and how modules interact for:
|
|
|
|
| Area | Sources |
|
|
| --- | --- |
|
|
| Backend | this repo — `src/app.module.ts`, `src/modules/` |
|
|
| Frontend web | sibling `trackgo-fe/apps/web` |
|
|
| Frontend landing | sibling `trackgo-fe/apps/landing` (public SPA, not the ERP) |
|
|
| Mobile | sibling `trackgo_mobile` |
|
|
|
|
Do **not** write customer how-tos here — those belong in `trackgo-fe/apps/docs-dev`.
|
|
|
|
## Layout
|
|
|
|
Prefer these folders under `docs/`:
|
|
|
|
```text
|
|
docs/
|
|
backend/
|
|
frontend-web/
|
|
frontend-landing/
|
|
mobile/
|
|
api.md # keep existing API reference
|
|
report-*.md # keep existing report docs
|
|
```
|
|
|
|
When adding pages:
|
|
|
|
1. Create the markdown under the matching folder.
|
|
2. Register it in `mkdocs.yml` `nav`.
|
|
3. Set `site_name` to TrackGo (it may still say `Concourse CI` — rename when you touch nav).
|
|
|
|
Preview: Docker TechDocs command in `docs/readme.md`.
|
|
|
|
## Ground in code
|
|
|
|
- Backend modules from `src/app.module.ts`: Auth, Users, Privileges, Configuration, Sales, Field, Reports.
|
|
- Web menus / RBAC keys: `trackgo-fe/apps/web/src/apps/main/layouts/data/menu.data.ts`.
|
|
- Mobile routes: `trackgo_mobile/lib/config/router.dart` (login, home, plan, customers, check-in, payment).
|
|
- Cross-read sibling repos; do not invent features. Brief vs code → follow code or **Coming soon**.
|
|
|
|
## Style
|
|
|
|
- No emoji.
|
|
- Diagrams / sequences: PlantUML only.
|
|
|
|
````markdown
|
|
```plantuml
|
|
@startuml
|
|
Alice -> Bob: request
|
|
Bob --> Alice: response
|
|
@enduml
|
|
```
|
|
````
|
|
|
|
```text
|
|
# BAD — user how-to in MkDocs
|
|
docs/how-to-create-invoice.md
|
|
|
|
# BAD — Mermaid or emoji
|
|
```mermaid
|
|
```
|
|
"🚀 Getting Started"
|
|
|
|
# GOOD
|
|
docs/backend/architecture.md
|
|
docs/frontend-web/modules.md
|
|
```
|