Stephan Lo
a7fb376157
Added two complementary quick-start guides to help new contributors get productive quickly without reading extensive documentation. DOCUMENTOR-GUIDE.md: - Quick-start guide for new documentation contributors - Covers essential workflows: local dev, testing, committing - Provides command reference for common tasks - Links to detailed documentation platform guides - Targets: writers, editors, content contributors - Goal: Productive in 5 minutes README-ARCHITECTURE.md: - Quick-start guide for architecture diagram contributors - Explains LikeC4 setup and project structure - Covers both edp-likec4 (platform) and doc-likec4 (meta-docs) projects - Provides regeneration workflow for webcomponents - Targets: architects, system designers, technical writers - Goal: Productive diagram editing in 5 minutes These guides complement the detailed documentation in content/en/docs/documentation/ by providing a fast-track onboarding path. New contributors can start with these quick-start guides and refer to detailed documentation as needed. Documentation hierarchy: 1. Quick-start (these guides) - Get started in minutes 2. Full guides (content/en/docs/documentation/) - Comprehensive workflows 3. Architecture diagrams - Visual learning and exploration Benefits: - Reduced onboarding time for new team members - Self-service documentation for common tasks - Clear separation between quick reference and detailed guides - Consistent documentation patterns across roles
8.4 KiB
8.4 KiB
Documentation Platform - Visual Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTATION REPOSITORY STRUCTURE │
└─────────────────────────────────────────────────────────────────────────────┘
📁 Repository Root
│
├── 📁 resources/
│ │
│ ├── 📁 edp-likec4/ ← Platform Architecture
│ │ ├── documentation-platform.c4 (Models for EDP systems)
│ │ ├── views.c4
│ │ ├── models/
│ │ └── views/
│ │
│ └── 📁 doc-likec4/ ← Documentation Platform Architecture
│ ├── documentation-platform.c4 (Models for this doc system)
│ ├── views.c4
│ ├── likec4.config.json
│ ├── package.json
│ └── README.md
│
├── 📁 content/en/docs/
│ │
│ ├── 📁 architecture/ ← Platform Architecture Docs
│ │ ├── highlevelarch.md
│ │ └── setup.md
│ │
│ └── 📁 documentation/ ← Documentation About Documentation
│ ├── _index.md (Overview for Documentors)
│ ├── local-development.md (How to work locally)
│ ├── testing.md (Quality assurance)
│ ├── cicd.md (CI/CD pipeline)
│ ├── publishing.md (Deployment to edge)
│ └── quick-reference.md (Cheat sheet)
│
├── 📄 Taskfile.yml ← Build Automation
├── 📄 .github/workflows/test.yml ← CI Pipeline
├── 📄 k8s-deployment.yaml ← Kubernetes Config
├── 📄 edgeconnectdeployment.yaml ← Edge Deployment Config
├── 📄 Dockerfile ← Container Definition
└── 📄 README-ARCHITECTURE.md ← This Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTOR WORKFLOW │
└─────────────────────────────────────────────────────────────────────────────┘
👤 Documentor
│
├──> 1. Write Content
│ └── content/en/docs/**/*.md
│
├──> 2. Create Architecture Models
│ └── resources/doc-likec4/*.c4
│ resources/edp-likec4/*.c4
│
├──> 3. Local Development
│ └── task serve
│ http://localhost:1313
│
├──> 4. Test Locally
│ └── task test:quick
│ - Build validation
│ - Markdown lint
│
├──> 5. Commit & Push
│ └── git push origin feature-branch
│
└──> 6. CI/CD Pipeline
├── GitHub Actions
│ ├── Build Test
│ ├── Markdown Lint
│ ├── HTML Validation
│ └── Link Checking
│
├── Container Build
│ └── Docker Image
│
└── Edge Deployment
└── Kubernetes on Munich Cloudlet
└── http://<external-ip>
┌─────────────────────────────────────────────────────────────────────────────┐
│ ARCHITECTURE VISUALIZATION │
└─────────────────────────────────────────────────────────────────────────────┘
Two Separate LikeC4 Projects:
┌──────────────────────────────┐ ┌──────────────────────────────┐
│ resources/edp-likec4/ │ │ resources/doc-likec4/ │
│ ───────────────────── │ │ ───────────────────── │
│ │ │ │
│ Platform Architecture │ │ Documentation Platform │
│ ──────────────────── │ │ ──────────────────── │
│ │ │ │
│ • Systems │ │ • Hugo/Docsy │
│ • Services │ │ • LikeC4 Integration │
│ • Infrastructure │ │ • Taskfile │
│ • Deployment Environments │ │ • GitHub Actions │
│ │ │ • Edge Deployment │
│ What we BUILD │ │ How we DOCUMENT │
│ │ │ │
└──────────────────────────────┘ └──────────────────────────────┘
│ │
│ │
▼ ▼
content/en/docs/ content/en/docs/
architecture/ documentation/
┌─────────────────────────────────────────────────────────────────────────────┐
│ QUICK START │
└─────────────────────────────────────────────────────────────────────────────┘
For New Documentors:
1. 📖 Read the Guide
→ Open: content/en/docs/documentation/_index.md
→ Or browse: http://localhost:1313/docs/documentation/
2. 🚀 Start Development
$ task serve
3. 📊 View Architecture
$ cd resources/doc-likec4
$ npm install
$ npm start
→ Opens: http://localhost:5173
4. ✅ Test Your Changes
$ task test:quick
5. 📚 Reference
→ Quick Reference: content/en/docs/documentation/quick-reference.md
┌─────────────────────────────────────────────────────────────────────────────┐
│ AVAILABLE VIEWS │
└─────────────────────────────────────────────────────────────────────────────┘
In resources/doc-likec4/views.c4:
• overview → Complete system overview
• localDevelopment → Documentor workflow with Taskfile
• cicdPipeline → Automated testing via GitHub Actions
• deploymentFlow → Edge deployment process
• fullWorkflow → End-to-end content → production
• testingCapabilities → All automated tests
Embed in Markdown:
{{< likec4-view view="overview" project="documentation-platform" >}}