Stephan Lo
9aea2a3583
Created a complete documentation system for new documentors, including
interactive architecture diagrams and step-by-step guides for all documentation
workflows.
New LikeC4 architecture project (resources/doc-likec4/):
- Created documentation-platform.c4 model with 252 lines covering:
* Actors: documentor, reviewer, CI system, edge platform
* Tools: Hugo, LikeC4, Git, VS Code, markdownlint, htmltest
* Processes: local development, testing, CI/CD pipeline
* Repositories: git repo, cloudlet registry
- Defined 6 comprehensive views:
* overview: Complete documentation platform ecosystem
* localDevelopment: Local writing and preview workflow
* cicdPipeline: Automated testing and validation
* deploymentFlow: From commit to production
* fullWorkflow: End-to-end documentation lifecycle
* testingCapabilities: Quality assurance toolchain
New documentation pages (content/en/docs/documentation/):
- _index.md: Overview and introduction for new documentors
- local-development.md: Setting up local environment, live preview
- testing.md: Running markdown, HTML, and link validation
- cicd.md: Understanding automated CI/CD pipeline
- publishing.md: Deployment to Edge Connect Munich cloudlet
- quick-reference.md: Command reference and common tasks
Hugo shortcode for embedding LikeC4 diagrams:
- Created layouts/shortcodes/likec4-view.html
- Supports loading state with animated indicator
- Graceful error handling for missing views
- Automatic shadow DOM checking to ensure webcomponent loaded
- Usage: {{< likec4-view view="viewId" project="projectName" >}}
Supporting documentation:
- resources/LIKEC4-REGENERATION.md: Guide for regenerating webcomponents
- All diagrams are interactive and explorable in the browser
- Views include zoom, pan, and element inspection
This implementation provides:
1. Self-documenting documentation platform ("meta-documentation")
2. Visual learning for complex workflows via interactive diagrams
3. Clear separation of concerns (6 focused views vs 1 overwhelming diagram)
4. Onboarding path for new team members
5. Living architecture documentation that evolves with the platform
All new documentation passes markdown linting and builds successfully.
1.4 KiB
1.4 KiB
| title | linkTitle | weight | description |
|---|---|---|---|
| Documentation About Documentation | Documentation | 10 | Learn how to create, maintain, and publish documentation for the developer platform. |
Welcome to the meta-documentation! This section explains how our documentation platform works and guides you through the documentor role.
What is a Documentor?
A Documentor is responsible for creating, maintaining, and publishing the developer platform documentation. This includes:
- Writing and updating content in Markdown
- Creating architecture diagrams with LikeC4
- Testing locally before committing
- Following the CI/CD pipeline to production
Documentation Platform Architecture
Our documentation is built on a modern stack:
- Hugo with the Docsy theme for static site generation
- LikeC4 for architecture visualization
- Taskfile for local development automation
- GitHub Actions for continuous testing
- Edge deployment for hosting
System Overview
{{< likec4-view view="overview" project="documentation-platform" >}}
This high-level view shows all major components of the documentation platform.
Getting Started
Continue to the next sections to learn about:
- Local Development - How to work on documentation locally
- Testing - Quality assurance processes
- CI/CD Pipeline - Automated testing and deployment
- Publishing - How documentation reaches production