From a7fb376157807e12bce8cb631bd8177195b6b717 Mon Sep 17 00:00:00 2001 From: Stephan Lo Date: Fri, 7 Nov 2025 11:53:31 +0100 Subject: [PATCH] docs: add quick-start guides for documentors and architects 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 --- DOCUMENTOR-GUIDE.md | 156 +++++++++++++++++++++++++++++++++++++++++ README-ARCHITECTURE.md | 92 ++++++++++++++++++++++++ 2 files changed, 248 insertions(+) create mode 100644 DOCUMENTOR-GUIDE.md create mode 100644 README-ARCHITECTURE.md diff --git a/DOCUMENTOR-GUIDE.md b/DOCUMENTOR-GUIDE.md new file mode 100644 index 0000000..2a66f11 --- /dev/null +++ b/DOCUMENTOR-GUIDE.md @@ -0,0 +1,156 @@ +# Documentation Platform - Visual Overview + +```text +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 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:// + + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 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" >}} +``` diff --git a/README-ARCHITECTURE.md b/README-ARCHITECTURE.md new file mode 100644 index 0000000..4efb435 --- /dev/null +++ b/README-ARCHITECTURE.md @@ -0,0 +1,92 @@ +# Documentation Platform - Overview + +This repository contains two distinct LikeC4 architecture documentation projects: + +## 📁 Structure + +### `resources/edp-likec4/` + +**Enterprise Developer Platform (EDP) Architecture** + +Contains architecture models for the platform itself - the systems, services, and infrastructure that make up the EDP. + +**Purpose:** Document what we build + +### `resources/doc-likec4/` + +**Documentation Platform Architecture** + +Contains architecture models that explain how this documentation system works - the Hugo/Docsy setup, CI/CD pipeline, and deployment process. + +**Purpose:** Document how we document (meta-documentation) + +## 🎯 For New Documentors + +If you're new to the documentor role and want to understand the documentation platform: + +1. **Read the documentation about documentation:** + → `content/en/docs/documentation/` + +2. **View the architecture diagrams:** + → The documentation pages embed interactive LikeC4 diagrams + +3. **Key sections:** + - [Overview](content/en/docs/documentation/_index.md) - What is a documentor? + - [Local Development](content/en/docs/documentation/local-development.md) - Get started + - [Testing](content/en/docs/documentation/testing.md) - Quality assurance + - [CI/CD](content/en/docs/documentation/cicd.md) - Automated pipeline + - [Publishing](content/en/docs/documentation/publishing.md) - Deployment to edge + +## 🚀 Quick Start + +```bash +# Start development server +task serve + +# Run tests +task test:quick + +# View architecture models +cd resources/doc-likec4 +npm install +npm start +``` + +## 📊 Architecture Views + +The documentation platform is visualized with these views: + +- **Overview** - Complete system overview +- **Local Development** - Documentor workflow +- **CI/CD Pipeline** - Automated testing +- **Deployment Flow** - Edge deployment process +- **Full Workflow** - End-to-end journey +- **Testing Capabilities** - Quality assurance + +## 🔗 Related Files + +- `Taskfile.yml` - Automation for local development and CI +- `.github/workflows/test.yml` - GitHub Actions CI pipeline +- `k8s-deployment.yaml` - Kubernetes deployment manifest +- `edgeconnectdeployment.yaml` - Edge Connect configuration +- `Dockerfile` - Container image definition + +## 📚 Documentation + +The documentation is built with: + +- **Hugo** - Static site generator +- **Docsy** - Documentation theme +- **LikeC4** - Architecture visualization +- **Task** - Build automation +- **GitHub Actions** - CI/CD +- **Edge Connect** - Deployment platform + +## 🎓 Learn More + +For complete information, browse to the documentation section after starting the server: + +```bash +task serve +# Then open: http://localhost:1313/docs/documentation/ +```