Stephan Lo
a7fb376157
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
92 lines
2.6 KiB
Markdown
92 lines
2.6 KiB
Markdown
# 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/
|
|
```
|