docs: add quick-start guides for documentors and architects
All checks were successful
ci / build (push) Successful in 56s
All checks were successful
ci / build (push) Successful in 56s
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
This commit is contained in:
parent
fb0ec3fd57
commit
a7fb376157
2 changed files with 248 additions and 0 deletions
156
DOCUMENTOR-GUIDE.md
Normal file
156
DOCUMENTOR-GUIDE.md
Normal file
|
|
@ -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://<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" >}}
|
||||
```
|
||||
92
README-ARCHITECTURE.md
Normal file
92
README-ARCHITECTURE.md
Normal file
|
|
@ -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/
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue