docs: replace 'Documentor' with 'Technical Writer' terminology

- Renamed README-documentor.md → README-technical-writer.md
- Updated all references from "Documentor" to "Technical Writer" across:
  - README files (README.md, README-developer.md, README-likec4.md)
  - Content pages (documentation section, homepage)
  - LikeC4 models (documentation-platform.c4 in both projects)
- Regenerated LikeC4 webcomponents with updated terminology
- Updated lowercase "documentor" to "technicalWriter" in model IDs

"Technical Writer" is the proper English term for documentation contributors,
replacing the non-standard "Documentor" terminology.
This commit is contained in:
Stephan Lo 2025-11-07 15:57:14 +01:00
parent 9e509ed265
commit df439058a9
13 changed files with 147 additions and 147 deletions

View file

@ -29,7 +29,7 @@ Devbox automatically installs all required tools:
- htmltest - htmltest
- go-task - go-task
> **Note:** For content contributors, see [README-documentor.md](./README-documentor.md) for a simplified guide. > **Note:** For content contributors, see [README-technicalWriter.md](./README-technicalWriter.md) for a simplified guide.
## 📚 Technology Stack ## 📚 Technology Stack
@ -302,7 +302,7 @@ hugo version
├── Dockerfile # Multi-stage container build ├── Dockerfile # Multi-stage container build
├── README.md # Main README ├── README.md # Main README
├── README-developer.md # This file ├── README-developer.md # This file
├── README-documentor.md # Guide for content contributors ├── README-technicalWriter.md # Guide for content contributors
├── README-likec4.md # LikeC4 architecture modeling guide ├── README-likec4.md # LikeC4 architecture modeling guide
└── RELEASE.md # Release process documentation └── RELEASE.md # Release process documentation
``` ```
@ -374,7 +374,7 @@ Parameters:
- `project` - `"architecture"` or `"documentation-platform"` - `project` - `"architecture"` or `"documentation-platform"`
- `title` - Optional custom title - `title` - Optional custom title
See [README-documentor.md](./README-documentor.md) for detailed LikeC4 workflow. See [README-technicalWriter.md](./README-technicalWriter.md) for detailed LikeC4 workflow.
## 🧪 Testing ## 🧪 Testing
@ -469,9 +469,9 @@ devbox shell --refresh
- [Devbox Documentation](https://www.jetify.com/devbox/docs/) - [Devbox Documentation](https://www.jetify.com/devbox/docs/)
**Project-specific guides:** **Project-specific guides:**
- [README-documentor.md](./README-documentor.md) - Content contributor guide - [README-technicalWriter.md](./README-technicalWriter.md) - Content contributor guide
- [TESTING.md](./TESTING.md) - Detailed testing documentation - [TESTING.md](./TESTING.md) - Detailed testing documentation
- [DOCUMENTOR-GUIDE.md](./DOCUMENTOR-GUIDE.md) - Quick reference for documentors - [DOCUMENTOR-GUIDE.md](./DOCUMENTOR-GUIDE.md) - Quick reference for technicalWriters
## 🤝 Contributing ## 🤝 Contributing

View file

@ -285,7 +285,7 @@ views {
### Documentation Platform (resources/doc-likec4/) ### Documentation Platform (resources/doc-likec4/)
- `overview` - Complete system overview - `overview` - Complete system overview
- `localDevelopment` - Documentor workflow - `localDevelopment` - Technical Writer workflow
- `cicdPipeline` - CI/CD pipeline - `cicdPipeline` - CI/CD pipeline
- `deploymentFlow` - Edge deployment - `deploymentFlow` - Edge deployment
- `fullWorkflow` - End-to-end workflow - `fullWorkflow` - End-to-end workflow
@ -379,5 +379,5 @@ npm install
## 🎓 Learn More ## 🎓 Learn More
For detailed usage in content creation, see: For detailed usage in content creation, see:
- [README-documentor.md](./README-documentor.md) - Content contributor guide - [README-technicalWriter.md](./README-technicalWriter.md) - Content contributor guide
- [content/en/docs/documentation/local-development.md](./content/en/docs/documentation/local-development.md) - Local development guide - [content/en/docs/documentation/local-development.md](./content/en/docs/documentation/local-development.md) - Local development guide

View file

@ -1,4 +1,4 @@
# Documentor Guide # Technical Writer Guide
Welcome! This guide helps you contribute to the IPCEI-CIS Developer Framework documentation. Welcome! This guide helps you contribute to the IPCEI-CIS Developer Framework documentation.

View file

@ -13,9 +13,9 @@ This repository contains the comprehensive documentation for the IPCEI-CIS Devel
## Quick Start ## Quick Start
### For Documentors (Content Writers) ### For Technical Writers (Content Writers)
If you want to contribute to the documentation, see **[README-documentor.md](./README-documentor.md)** for detailed instructions. If you want to contribute to the documentation, see **[README-technicalWriter.md](./README-technicalWriter.md)** for detailed instructions.
**Quick start:** **Quick start:**
@ -50,7 +50,7 @@ The documentation is published at:
│ └── en/ │ └── en/
│ ├── docs/ # Main documentation │ ├── docs/ # Main documentation
│ │ ├── architecture/ # Architecture docs with LikeC4 │ │ ├── architecture/ # Architecture docs with LikeC4
│ │ ├── documentation/ # Documentor guides │ │ ├── documentation/ # Technical Writer guides
│ │ └── v1/ # Legacy documentation │ │ └── v1/ # Legacy documentation
│ └── blog/ # Blog posts │ └── blog/ # Blog posts
├── resources/ # LikeC4 architecture models ├── resources/ # LikeC4 architecture models
@ -124,7 +124,7 @@ Install the following tools:
We welcome contributions! Please: We welcome contributions! Please:
1. Read [README-documentor.md](./README-documentor.md) for documentation guidelines 1. Read [README-technicalWriter.md](./README-technicalWriter.md) for documentation guidelines
2. Check existing [ADRs](./content/en/docs/decisions/) for architectural context 2. Check existing [ADRs](./content/en/docs/decisions/) for architectural context
3. Create a branch for your changes 3. Create a branch for your changes
4. Run `task test` before committing 4. Run `task test` before committing
@ -150,4 +150,4 @@ We welcome contributions! Please:
--- ---
For detailed documentation contribution guidelines, see [README-documentor.md](./README-documentor.md). For detailed documentation contribution guidelines, see [README-technicalWriter.md](./README-technicalWriter.md).

View file

@ -22,7 +22,7 @@ Explore the platform's architecture with interactive C4 diagrams. Understand the
**Dive into the architecture →** **Dive into the architecture →**
{{% /blocks/feature %}} {{% /blocks/feature %}}
{{% blocks/feature icon="fa-solid fa-book-open" title="Documentor Guide" url="/docs/documentation/" %}} {{% blocks/feature icon="fa-solid fa-book-open" title="Technical Writer Guide" url="/docs/documentation/" %}}
Learn how to contribute to this documentation. Write content, test locally, and understand the CI/CD pipeline. Learn how to contribute to this documentation. Write content, test locally, and understand the CI/CD pipeline.
**Start documenting →** **Start documenting →**
@ -73,7 +73,7 @@ Access the previous version of our documentation including historical project in
## Get Started ## Get Started
Whether you're a **platform engineer**, **application developer**, or **documentor**, we have resources for you: Whether you're a **platform engineer**, **application developer**, or **technicalWriter**, we have resources for you:
- 📖 Read the [Architecture Overview](/docs/architecture/highlevelarch/) to understand the system - 📖 Read the [Architecture Overview](/docs/architecture/highlevelarch/) to understand the system
- 🏗️ Explore [Platform Components](/docs/architecture/) and their interactions - 🏗️ Explore [Platform Components](/docs/architecture/) and their interactions

View file

@ -6,11 +6,11 @@ description: >
Learn how to create, maintain, and publish documentation for the developer platform. Learn how to create, maintain, and publish documentation for the developer platform.
--- ---
Welcome to the meta-documentation! This section explains how our documentation platform works and guides you through the documentor role. Welcome to the meta-documentation! This section explains how our documentation platform works and guides you through the technicalWriter role.
## What is a Documentor? ## What is a Technical Writer?
A **Documentor** is responsible for creating, maintaining, and publishing the developer platform documentation. This includes: A **Technical Writer** is responsible for creating, maintaining, and publishing the developer platform documentation. This includes:
- Writing and updating content in Markdown - Writing and updating content in Markdown
- Creating architecture diagrams with LikeC4 - Creating architecture diagrams with LikeC4

View file

@ -3,7 +3,7 @@ title: "Local Development"
linkTitle: "Local Development" linkTitle: "Local Development"
weight: 20 weight: 20
description: > description: >
Set up your local environment and learn the documentor workflow. Set up your local environment and learn the technicalWriter workflow.
--- ---
## Prerequisites ## Prerequisites
@ -193,7 +193,7 @@ For comprehensive testing, including link checking:
task test task test
``` ```
## Tips for Documentors ## Tips for Technical Writers
1. **Write in present tense** - "The system processes..." not "The system will process..." 1. **Write in present tense** - "The system processes..." not "The system will process..."
2. **Use code blocks** with syntax highlighting 2. **Use code blocks** with syntax highlighting

View file

@ -166,7 +166,7 @@ Documentation is now accessible:
### End-to-End Process ### End-to-End Process
1. **Documentor writes content** (Markdown, LikeC4 models) 1. **Technical Writer writes content** (Markdown, LikeC4 models)
2. **Local testing** with `task serve` and `task test` 2. **Local testing** with `task serve` and `task test`
3. **Commit and push** to Git repository 3. **Commit and push** to Git repository
4. **GitHub Actions triggered** on push to main 4. **GitHub Actions triggered** on push to main
@ -336,4 +336,4 @@ The deployment process is automated and reliable:
**Kubernetes orchestration** - Reliable, scalable platform **Kubernetes orchestration** - Reliable, scalable platform
**Simple rollback** - Easy to recover from issues **Simple rollback** - Easy to recover from issues
As a documentor, focus on content quality. The platform handles deployment automatically! 🚀 As a technicalWriter, focus on content quality. The platform handles deployment automatically! 🚀

View file

@ -3,7 +3,7 @@ title: "Quick Reference"
linkTitle: "Quick Reference" linkTitle: "Quick Reference"
weight: 60 weight: 60
description: > description: >
Cheat sheet for common documentor tasks. Cheat sheet for common technicalWriter tasks.
--- ---
## Common Commands ## Common Commands

View file

@ -4,7 +4,7 @@ This folder contains LikeC4 architecture models that document the documentation
## Purpose ## Purpose
These models help new **Documentors** understand: These models help new **Technical Writers** understand:
- How the documentation platform works - How the documentation platform works
- The local development workflow - The local development workflow
@ -24,7 +24,7 @@ High-level view of the entire documentation platform, showing all major componen
### Local Development Workflow ### Local Development Workflow
How a documentor works locally with content, Taskfile, and Hugo server. How a technicalWriter works locally with content, Taskfile, and Hugo server.
### CI/CD Pipeline ### CI/CD Pipeline

View file

@ -39,7 +39,7 @@ specification {
model { model {
// === Personas === // === Personas ===
documentor = person 'Documentor' { technicalWriter = person 'Technical Writer' {
description 'Content creator and maintainer of the developer platform documentation' description 'Content creator and maintainer of the developer platform documentation'
technology 'Hugo, Markdown, LikeC4' technology 'Hugo, Markdown, LikeC4'
} }
@ -151,16 +151,16 @@ deploymentEnv = system 'Deployment Environment' {
} }
} }
// === Relationships: Documentor Workflow === // === Relationships: Technical Writer Workflow ===
documentor -> contentRepo.contentPages 'writes documentation' { technicalWriter -> contentRepo.contentPages 'writes documentation' {
description 'Creates and updates Markdown content' description 'Creates and updates Markdown content'
} }
documentor -> contentRepo.archModels 'creates architecture models' { technicalWriter -> contentRepo.archModels 'creates architecture models' {
description 'Defines C4 models with LikeC4 DSL' description 'Defines C4 models with LikeC4 DSL'
} }
documentor -> taskfile 'executes local tasks' { technicalWriter -> taskfile 'executes local tasks' {
description 'task serve, task build, task test' description 'task serve, task build, task test'
} }
@ -244,7 +244,7 @@ deploymentEnv.k8sCluster.docDeployment -> deploymentEnv.k8sCluster.docService 'e
description 'Port 80' description 'Port 80'
} }
documentor -> deploymentEnv.k8sCluster.docService 'views published docs' { technicalWriter -> deploymentEnv.k8sCluster.docService 'views published docs' {
description 'HTTPS access to live documentation' description 'HTTPS access to live documentation'
} }
@ -256,11 +256,11 @@ views {
view overview of docPlatform { view overview of docPlatform {
title 'Documentation Platform Overview' title 'Documentation Platform Overview'
description 'High-level overview of the Hugo-based documentation platform for documentors' description 'High-level overview of the Hugo-based documentation platform for technicalWriters'
include * include *
style documentor { style technicalWriter {
color green color green
} }
style docPlatform { style docPlatform {
@ -270,9 +270,9 @@ views {
view localDevelopment of docPlatform { view localDevelopment of docPlatform {
title 'Local Development Workflow' title 'Local Development Workflow'
description 'How a documentor works locally with the documentation' description 'How a technicalWriter works locally with the documentation'
include documentor include technicalWriter
include docPlatform include docPlatform
include docPlatform.contentRepo -> * include docPlatform.contentRepo -> *
include docPlatform.hugoSite include docPlatform.hugoSite
@ -280,7 +280,7 @@ views {
include docPlatform.taskfile include docPlatform.taskfile
include docPlatform.devServer include docPlatform.devServer
style documentor { style technicalWriter {
color green color green
} }
style docPlatform.taskfile { style docPlatform.taskfile {
@ -317,7 +317,7 @@ views {
include deploymentEnv include deploymentEnv
include deploymentEnv.edgeConnect include deploymentEnv.edgeConnect
include deploymentEnv.k8sCluster -> * include deploymentEnv.k8sCluster -> *
include documentor include technicalWriter
style deploymentEnv { style deploymentEnv {
color muted color muted
@ -328,10 +328,10 @@ views {
} }
view fullWorkflow { view fullWorkflow {
title 'Complete Documentor Workflow' title 'Complete Technical Writer Workflow'
description 'End-to-end view from content creation to published documentation' description 'End-to-end view from content creation to published documentation'
include documentor include technicalWriter
include docPlatform.contentRepo include docPlatform.contentRepo
include docPlatform.taskfile include docPlatform.taskfile
include cicdPipeline.githubActions include cicdPipeline.githubActions
@ -339,7 +339,7 @@ views {
include deploymentEnv.edgeConnect include deploymentEnv.edgeConnect
include deploymentEnv.k8sCluster include deploymentEnv.k8sCluster
style documentor { style technicalWriter {
color green color green
} }
style docPlatform.taskfile { style docPlatform.taskfile {

View file

@ -4,7 +4,7 @@
model { model {
// === Personas === // === Personas ===
documentor = person 'Documentor' { technicalWriter = person 'Technical Writer' {
description 'Content creator and maintainer of the developer platform documentation' description 'Content creator and maintainer of the developer platform documentation'
technology 'Hugo, Markdown, LikeC4' technology 'Hugo, Markdown, LikeC4'
} }
@ -116,16 +116,16 @@ deploymentEnv = system 'Deployment Environment' {
} }
} }
// === Relationships: Documentor Workflow === // === Relationships: Technical Writer Workflow ===
documentor -> contentRepo.contentPages 'writes documentation' { technicalWriter -> contentRepo.contentPages 'writes documentation' {
description 'Creates and updates Markdown content' description 'Creates and updates Markdown content'
} }
documentor -> contentRepo.archModels 'creates architecture models' { technicalWriter -> contentRepo.archModels 'creates architecture models' {
description 'Defines C4 models with LikeC4 DSL' description 'Defines C4 models with LikeC4 DSL'
} }
documentor -> taskfile 'executes local tasks' { technicalWriter -> taskfile 'executes local tasks' {
description 'task serve, task build, task test' description 'task serve, task build, task test'
} }
@ -209,7 +209,7 @@ deploymentEnv.k8sCluster.docDeployment -> deploymentEnv.k8sCluster.docService 'e
description 'Port 80' description 'Port 80'
} }
documentor -> deploymentEnv.k8sCluster.docService 'views published docs' { technicalWriter -> deploymentEnv.k8sCluster.docService 'views published docs' {
description 'HTTPS access to live documentation' description 'HTTPS access to live documentation'
} }
@ -221,11 +221,11 @@ views {
view overview of docPlatform { view overview of docPlatform {
title 'Documentation Platform Overview' title 'Documentation Platform Overview'
description 'High-level overview of the Hugo-based documentation platform for documentors' description 'High-level overview of the Hugo-based documentation platform for technicalWriters'
include * include *
style documentor { style technicalWriter {
color green color green
} }
style docPlatform { style docPlatform {
@ -235,9 +235,9 @@ views {
view localDevelopment of docPlatform { view localDevelopment of docPlatform {
title 'Local Development Workflow' title 'Local Development Workflow'
description 'How a documentor works locally with the documentation' description 'How a technicalWriter works locally with the documentation'
include documentor include technicalWriter
include docPlatform include docPlatform
include docPlatform.contentRepo -> * include docPlatform.contentRepo -> *
include docPlatform.hugoSite include docPlatform.hugoSite
@ -245,7 +245,7 @@ views {
include docPlatform.taskfile include docPlatform.taskfile
include docPlatform.devServer include docPlatform.devServer
style documentor { style technicalWriter {
color green color green
} }
style docPlatform.taskfile { style docPlatform.taskfile {
@ -282,7 +282,7 @@ views {
include deploymentEnv include deploymentEnv
include deploymentEnv.edgeConnect include deploymentEnv.edgeConnect
include deploymentEnv.k8sCluster -> * include deploymentEnv.k8sCluster -> *
include documentor include technicalWriter
style deploymentEnv { style deploymentEnv {
color muted color muted
@ -293,10 +293,10 @@ views {
} }
view fullWorkflow { view fullWorkflow {
title 'Complete Documentor Workflow' title 'Complete Technical Writer Workflow'
description 'End-to-end view from content creation to published documentation' description 'End-to-end view from content creation to published documentation'
include documentor include technicalWriter
include docPlatform.contentRepo include docPlatform.contentRepo
include docPlatform.taskfile include docPlatform.taskfile
include cicdPipeline.githubActions include cicdPipeline.githubActions
@ -304,7 +304,7 @@ views {
include deploymentEnv.edgeConnect include deploymentEnv.edgeConnect
include deploymentEnv.k8sCluster include deploymentEnv.k8sCluster
style documentor { style technicalWriter {
color green color green
} }
style docPlatform.taskfile { style docPlatform.taskfile {

File diff suppressed because one or more lines are too long