Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity
website-and-documentation/README-ARCHITECTURE.md
Stephan Lo a7fb376157 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
2025-11-07 11:53:31 +01:00

2.6 KiB
Raw Blame History

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:

🚀 Quick Start

# 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:

task serve
# Then open: http://localhost:1313/docs/documentation/