feat(doc-structure): documentation structure ready for team development or writing resp.
This commit is contained in:
parent
4935913002
commit
f0ca9bbce2
32 changed files with 1911 additions and 1714 deletions
10
resources/edp-likec4/models/context/documentation.c4
Normal file
10
resources/edp-likec4/models/context/documentation.c4
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
model {
|
||||
documentation = system 'Documentation' {
|
||||
description 'Documentation system for EDP LikeC4 platform.'
|
||||
technology 'Static Site Generator'
|
||||
icon tech:electron
|
||||
-> edp 'provides documentation for'
|
||||
platformdeveloper -> documentation "creates and maintains documentation"
|
||||
|
||||
}
|
||||
}
|
||||
|
|
@ -1,336 +0,0 @@
|
|||
// Documentation Platform Architecture Model
|
||||
// This model describes the Hugo-based documentation platform
|
||||
|
||||
model {
|
||||
|
||||
// === Personas ===
|
||||
technicalWriter = person 'Technical Writer' {
|
||||
description 'Content creator and maintainer of the developer platform documentation'
|
||||
technology 'Hugo, Markdown, LikeC4'
|
||||
}
|
||||
|
||||
// === Documentation Platform System ===
|
||||
docPlatform = system 'Documentation Platform' {
|
||||
description 'Hugo-based documentation system with integrated architecture visualization'
|
||||
|
||||
// Core Components
|
||||
hugoSite = component 'Hugo Site' {
|
||||
description 'Static site generator based on Hugo with Docsy theme'
|
||||
technology 'Hugo Extended, Docsy'
|
||||
}
|
||||
|
||||
contentRepo = repository 'Content Repository' {
|
||||
description 'Markdown files, images, and configuration'
|
||||
technology 'Git, Markdown'
|
||||
|
||||
contentPages = component 'Content Pages' {
|
||||
description 'Documentation pages in Markdown format'
|
||||
technology 'Markdown'
|
||||
}
|
||||
|
||||
archModels = component 'Architecture Models' {
|
||||
description 'LikeC4 architecture models and views'
|
||||
technology 'LikeC4 DSL'
|
||||
}
|
||||
|
||||
assets = component 'Static Assets' {
|
||||
description 'CSS, JavaScript, images, fonts'
|
||||
technology 'CSS, JavaScript'
|
||||
}
|
||||
}
|
||||
|
||||
likec4Integration = component 'LikeC4 Integration' {
|
||||
description 'Architecture diagram visualization embedded in documentation'
|
||||
technology 'LikeC4, Web Components'
|
||||
}
|
||||
|
||||
// Build & Development Tools
|
||||
taskfile = tool 'Taskfile' {
|
||||
description 'Task automation for local development, build, and testing'
|
||||
technology 'Task (go-task)'
|
||||
}
|
||||
|
||||
devServer = process 'Development Server' {
|
||||
description 'Local Hugo server with hot reload for content development'
|
||||
technology 'Hugo Server'
|
||||
}
|
||||
}
|
||||
|
||||
// === CI/CD Pipeline ===
|
||||
cicdPipeline = system 'CI/CD Pipeline' {
|
||||
description 'Automated testing and deployment pipeline'
|
||||
|
||||
githubActions = process 'GitHub Actions' {
|
||||
description 'Automated testing workflow on push/PR'
|
||||
technology 'GitHub Actions'
|
||||
|
||||
testBuild = component 'Build Test' {
|
||||
description 'Hugo build validation'
|
||||
technology 'Hugo'
|
||||
}
|
||||
|
||||
testMarkdown = component 'Markdown Lint' {
|
||||
description 'Markdown syntax and style checking'
|
||||
technology 'markdownlint'
|
||||
}
|
||||
|
||||
testHtml = component 'HTML Validation' {
|
||||
description 'Generated HTML validation'
|
||||
technology 'htmlvalidate'
|
||||
}
|
||||
|
||||
testLinks = component 'Link Checker' {
|
||||
description 'Broken link detection'
|
||||
technology 'htmltest'
|
||||
}
|
||||
}
|
||||
|
||||
containerBuild = process 'Container Build' {
|
||||
description 'OCI/Docker image creation with Hugo site'
|
||||
technology 'Docker'
|
||||
}
|
||||
}
|
||||
|
||||
// === Deployment ===
|
||||
deploymentEnv = system 'Deployment Environment' {
|
||||
description 'Edge deployment infrastructure'
|
||||
|
||||
edgeConnect = system 'Edge Connect' {
|
||||
description 'Edge deployment orchestration platform'
|
||||
technology 'EdgeConnect'
|
||||
}
|
||||
|
||||
k8sCluster = system 'Kubernetes Cluster' {
|
||||
description 'K8s cluster on edge cloudlet (Munich)'
|
||||
technology 'Kubernetes'
|
||||
|
||||
docService = component 'Documentation Service' {
|
||||
description 'LoadBalancer service exposing docs on port 80'
|
||||
technology 'K8s Service'
|
||||
}
|
||||
|
||||
docDeployment = component 'Documentation Deployment' {
|
||||
description 'Pod running Hugo-generated static site'
|
||||
technology 'K8s Deployment, Nginx'
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// === Relationships: Technical Writer Workflow ===
|
||||
technicalWriter -> contentRepo.contentPages 'writes documentation' {
|
||||
description 'Creates and updates Markdown content'
|
||||
}
|
||||
|
||||
technicalWriter -> contentRepo.archModels 'creates architecture models' {
|
||||
description 'Defines C4 models with LikeC4 DSL'
|
||||
}
|
||||
|
||||
technicalWriter -> taskfile 'executes local tasks' {
|
||||
description 'task serve, task build, task test'
|
||||
}
|
||||
|
||||
// === Relationships: Local Development ===
|
||||
taskfile -> devServer 'starts' {
|
||||
description 'task serve'
|
||||
}
|
||||
|
||||
devServer -> hugoSite 'renders' {
|
||||
description 'Live reload on content changes'
|
||||
}
|
||||
|
||||
hugoSite -> contentRepo 'reads content from' {
|
||||
description 'Processes Markdown and templates'
|
||||
}
|
||||
|
||||
hugoSite -> likec4Integration 'integrates' {
|
||||
description 'Embeds architecture diagrams'
|
||||
}
|
||||
|
||||
likec4Integration -> contentRepo.archModels 'visualizes' {
|
||||
description 'Renders C4 models as interactive diagrams'
|
||||
}
|
||||
|
||||
// === Relationships: Testing ===
|
||||
taskfile -> githubActions.testBuild 'can run locally' {
|
||||
description 'task test:build'
|
||||
}
|
||||
|
||||
taskfile -> githubActions.testMarkdown 'can run locally' {
|
||||
description 'task test:markdown'
|
||||
}
|
||||
|
||||
taskfile -> githubActions.testHtml 'can run locally' {
|
||||
description 'task test:html'
|
||||
}
|
||||
|
||||
taskfile -> githubActions.testLinks 'can run locally' {
|
||||
description 'task test:links'
|
||||
}
|
||||
|
||||
// === Relationships: CI/CD ===
|
||||
contentRepo -> githubActions 'triggers on push/PR' {
|
||||
description 'Webhook on main branch'
|
||||
}
|
||||
|
||||
githubActions.testBuild -> hugoSite 'builds' {
|
||||
description 'hugo --gc --minify'
|
||||
}
|
||||
|
||||
githubActions.testMarkdown -> contentRepo.contentPages 'validates' {
|
||||
description 'Lints Markdown files'
|
||||
}
|
||||
|
||||
githubActions.testHtml -> hugoSite 'validates output' {
|
||||
description 'Checks generated HTML'
|
||||
}
|
||||
|
||||
githubActions.testLinks -> hugoSite 'checks links in' {
|
||||
description 'Detects broken links'
|
||||
}
|
||||
|
||||
githubActions -> containerBuild 'triggers on success' {
|
||||
description 'Builds Docker image with Hugo output'
|
||||
}
|
||||
|
||||
containerBuild -> hugoSite 'packages' {
|
||||
description 'public/ directory served by Nginx'
|
||||
}
|
||||
|
||||
// === Relationships: Deployment ===
|
||||
containerBuild -> deploymentEnv.edgeConnect 'pushes image to' {
|
||||
description 'Tagged container image'
|
||||
}
|
||||
|
||||
deploymentEnv.edgeConnect -> deploymentEnv.k8sCluster 'deploys to' {
|
||||
description 'Via edgeconnectdeployment.yaml'
|
||||
}
|
||||
|
||||
deploymentEnv.k8sCluster.docDeployment -> deploymentEnv.k8sCluster.docService 'exposed by' {
|
||||
description 'Port 80'
|
||||
}
|
||||
|
||||
technicalWriter -> deploymentEnv.k8sCluster.docService 'views published docs' {
|
||||
description 'HTTPS access to live documentation'
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
// === Views ===
|
||||
|
||||
views {
|
||||
|
||||
view overview of docPlatform {
|
||||
title 'Documentation Platform Overview'
|
||||
description 'High-level overview of the Hugo-based documentation platform for technicalWriters'
|
||||
|
||||
include *
|
||||
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform {
|
||||
color blue
|
||||
}
|
||||
}
|
||||
|
||||
view localDevelopment of docPlatform {
|
||||
title 'Local Development Workflow'
|
||||
description 'How a technicalWriter works locally with the documentation'
|
||||
|
||||
include technicalWriter
|
||||
include docPlatform
|
||||
include docPlatform.contentRepo -> *
|
||||
include docPlatform.hugoSite
|
||||
include docPlatform.likec4Integration
|
||||
include docPlatform.taskfile
|
||||
include docPlatform.devServer
|
||||
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform.taskfile {
|
||||
color amber
|
||||
}
|
||||
style docPlatform.devServer {
|
||||
color amber
|
||||
}
|
||||
}
|
||||
|
||||
view cicdPipeline of cicdPipeline {
|
||||
title 'CI/CD Pipeline'
|
||||
description 'Automated testing and container build process'
|
||||
|
||||
include cicdPipeline
|
||||
include cicdPipeline.githubActions -> *
|
||||
include cicdPipeline.containerBuild
|
||||
include docPlatform.contentRepo
|
||||
include docPlatform.hugoSite
|
||||
|
||||
style cicdPipeline.githubActions {
|
||||
color blue
|
||||
}
|
||||
style cicdPipeline.containerBuild {
|
||||
color indigo
|
||||
}
|
||||
}
|
||||
|
||||
view deploymentFlow {
|
||||
title 'Deployment to Edge Environment'
|
||||
description 'How the documentation is deployed to the edge infrastructure'
|
||||
|
||||
include cicdPipeline.containerBuild
|
||||
include deploymentEnv
|
||||
include deploymentEnv.edgeConnect
|
||||
include deploymentEnv.k8sCluster -> *
|
||||
include technicalWriter
|
||||
|
||||
style deploymentEnv {
|
||||
color muted
|
||||
}
|
||||
style deploymentEnv.k8sCluster {
|
||||
color secondary
|
||||
}
|
||||
}
|
||||
|
||||
view fullWorkflow {
|
||||
title 'Complete Technical Writer Workflow'
|
||||
description 'End-to-end view from content creation to published documentation'
|
||||
|
||||
include technicalWriter
|
||||
include docPlatform.contentRepo
|
||||
include docPlatform.taskfile
|
||||
include cicdPipeline.githubActions
|
||||
include cicdPipeline.containerBuild
|
||||
include deploymentEnv.edgeConnect
|
||||
include deploymentEnv.k8sCluster
|
||||
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform.taskfile {
|
||||
color amber
|
||||
}
|
||||
style cicdPipeline.githubActions {
|
||||
color blue
|
||||
}
|
||||
style deploymentEnv.k8sCluster {
|
||||
color secondary
|
||||
}
|
||||
}
|
||||
|
||||
view testingCapabilities of cicdPipeline.githubActions {
|
||||
title 'Testing Capabilities'
|
||||
description 'All automated tests that ensure documentation quality'
|
||||
|
||||
include *
|
||||
include docPlatform.hugoSite
|
||||
include docPlatform.contentRepo.contentPages
|
||||
include docPlatform.taskfile
|
||||
|
||||
style cicdPipeline.githubActions {
|
||||
color blue
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
views {
|
||||
view components-template-documentation of documentation {
|
||||
description 'Documentation System Context View'
|
||||
include documentation
|
||||
include platformdeveloper with {
|
||||
title 'Technical Writer'
|
||||
description 'Could be an engineer, but in this case it\'s the Technical Writer'
|
||||
}
|
||||
// autoLayout LeftRight 120 110
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue