Documentation Technical Workflow¶

This diagram illustrates how the Daktela documentation system works from a technical perspective.

Documentation Creation Sources¶

![Documentation Creation Sources diagram](images/documentation-creation-sources.svg){ .diagram-img }

Review & Deployment Pipeline¶

![Review & Deployment Pipeline diagram](images/review-deployment-pipeline.svg){ .diagram-img }

Documentation Creation Workflows¶

1. ClickUp Workflow¶

PRDs and feature specifications are managed in ClickUp with ticket numbers.

Step	Action
1	Create ClickUp task with ticket number (e.g., `Feature #123456`)
2	Add requirements, specs, and context to task description
3	Ticket number links all related work across systems

Ticket number formats supported: - Task name: Feature #123456 - Custom field "Ticket Number": 123456 - ClickUp Custom ID: PROJ-123

2. GitLab Codebase Workflow¶

Code commits reference ticket numbers to link implementation details.

Step	Action
1	Developers implement feature in codebase
2	Commits include ticket reference: `fix: update login flow #123456`
3	Generator searches commits by ticket number

3. Figma Workflow¶

UI/UX designs provide visual documentation and screenshots.

Step	Action
1	Designers create mockups in Figma
2	Generator exports screenshots with `--export-screenshots` flag
3	Images are embedded in generated documentation

4. Documentation Generator¶

The generator aggregates all sources into draft documentation.

# Generate docs for ticket #123456
./generate_docs.py 123456 -p contact-centre -v 2025.2

# With Figma screenshots
./generate_docs.py 123456 -p contact-centre -t feature --export-screenshots

Required API tokens: - ClickUp: app.clickup.com/settings/apps - GitLab: gitlab.daktela.com/-/profile/personal_access_tokens - Figma: www.figma.com/settings (optional)

Component Details¶

Local Development¶

Component	Description
MkDocs	Static site generator for documentation
Material Theme	Modern, responsive documentation theme
mkdocs serve	Local preview server (http://localhost:8000)
Doc Generator	Aggregates ClickUp, GitLab, and Figma sources

CI/CD Pipeline¶

Stage	Action
Trigger	Push to `main` branch
Container	`squidfunk/mkdocs-material:latest`
Build	`mkdocs build` → `output/` directory
Deploy	`rsync -avzP --delete` to production

Infrastructure¶

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   ClickUp    │  │    GitLab    │  │    Figma     │
│  (PRDs &     │  │  (Commits &  │  │  (UI/UX      │
│   Tickets)   │  │   Code)      │  │   Designs)   │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └────────────────┬┴─────────────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  Doc Generator      │
              │  generate_docs.py   │
              └──────────┬──────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                     GitLab Repository                        │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   updates   │───▶│    main     │───▶│  CI/CD      │     │
│  │   branch    │ MR │   branch    │    │  Pipeline   │     │
│  └─────────────┘    └─────────────┘    └──────┬──────┘     │
└──────────────────────────────────────────────│──────────────┘
                                               │
                                               ▼
                              ┌────────────────────────────────┐
                              │     Production Server          │
                              │  vmakestest.daktela.com        │
                              │  ┌──────────────────────────┐  │
                              │  │   /opt/doc/              │  │
                              │  │   ├── en/                │  │
                              │  │   ├── cs/                │  │
                              │  │   └── assets/            │  │
                              │  └──────────────────────────┘  │
                              └────────────────────────────────┘

Quick Reference¶

Local preview:

mkdocs serve
# or using Docker:
docker run --rm -v "$(pwd):/docs" -p 8000:8000 squidfunk/mkdocs-material:latest serve -a 0.0.0.0:8000

Manual build:

./scripts/build-docs.sh

Key files: - mkdocs.yml - Main MkDocs configuration - .gitlab-ci.yml - CI/CD pipeline definition - .doc-generator/ - Documentation generator tool - docs/ - Source documentation (Markdown) - output/ - Built site (generated)

End-to-End Example¶

1. PM creates ClickUp task: "Add dark mode toggle #789012"
2. Developer commits: "feat: implement dark mode #789012"
3. Designer uploads Figma mockups for dark mode UI
                            ↓
4. Run: ./generate_docs.py 789012 -p contact-centre --export-screenshots
                            ↓
5. Generator outputs draft markdown with:
   - Feature description from ClickUp PRD
   - Technical details from GitLab commits
   - Screenshots from Figma designs
                            ↓
6. Author reviews, edits, runs mkdocs serve
7. Push to updates branch → Merge Request
8. Reviewer approves → Merge to main
9. CI/CD builds & deploys to production