Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity
website-and-documentation/content/en/docs/documentation/_index.md

44 lines
1.4 KiB
Markdown
Raw Normal View History

feat(docs): add comprehensive documentation platform architecture and guides 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.
2025-11-07 11:50:58 +01:00
---
title: "Documentation About Documentation"
linkTitle: "Documentation"
weight: 10
description: >
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:
1. [Local Development](local-development/) - How to work on documentation locally
2. [Testing](testing/) - Quality assurance processes
3. [CI/CD Pipeline](cicd/) - Automated testing and deployment
4. [Publishing](publishing/) - How documentation reaches production
Copy permalink