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:
parent
9e509ed265
commit
df439058a9
13 changed files with 147 additions and 147 deletions
|
|
@ -29,7 +29,7 @@ Devbox automatically installs all required tools:
|
|||
- htmltest
|
||||
- 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
|
||||
|
||||
|
|
@ -302,7 +302,7 @@ hugo version
|
|||
├── Dockerfile # Multi-stage container build
|
||||
├── README.md # Main README
|
||||
├── 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
|
||||
└── RELEASE.md # Release process documentation
|
||||
```
|
||||
|
|
@ -374,7 +374,7 @@ Parameters:
|
|||
- `project` - `"architecture"` or `"documentation-platform"`
|
||||
- `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
|
||||
|
||||
|
|
@ -469,9 +469,9 @@ devbox shell --refresh
|
|||
- [Devbox Documentation](https://www.jetify.com/devbox/docs/)
|
||||
|
||||
**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
|
||||
- [DOCUMENTOR-GUIDE.md](./DOCUMENTOR-GUIDE.md) - Quick reference for documentors
|
||||
- [DOCUMENTOR-GUIDE.md](./DOCUMENTOR-GUIDE.md) - Quick reference for technicalWriters
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
|
|
|
|||
|
|
@ -285,7 +285,7 @@ views {
|
|||
### Documentation Platform (resources/doc-likec4/)
|
||||
|
||||
- `overview` - Complete system overview
|
||||
- `localDevelopment` - Documentor workflow
|
||||
- `localDevelopment` - Technical Writer workflow
|
||||
- `cicdPipeline` - CI/CD pipeline
|
||||
- `deploymentFlow` - Edge deployment
|
||||
- `fullWorkflow` - End-to-end workflow
|
||||
|
|
@ -379,5 +379,5 @@ npm install
|
|||
## 🎓 Learn More
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Documentor Guide
|
||||
# Technical Writer Guide
|
||||
|
||||
Welcome! This guide helps you contribute to the IPCEI-CIS Developer Framework documentation.
|
||||
|
||||
10
README.md
10
README.md
|
|
@ -13,9 +13,9 @@ This repository contains the comprehensive documentation for the IPCEI-CIS Devel
|
|||
|
||||
## 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:**
|
||||
|
||||
|
|
@ -50,7 +50,7 @@ The documentation is published at:
|
|||
│ └── en/
|
||||
│ ├── docs/ # Main documentation
|
||||
│ │ ├── architecture/ # Architecture docs with LikeC4
|
||||
│ │ ├── documentation/ # Documentor guides
|
||||
│ │ ├── documentation/ # Technical Writer guides
|
||||
│ │ └── v1/ # Legacy documentation
|
||||
│ └── blog/ # Blog posts
|
||||
├── resources/ # LikeC4 architecture models
|
||||
|
|
@ -124,7 +124,7 @@ Install the following tools:
|
|||
|
||||
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
|
||||
3. Create a branch for your changes
|
||||
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).
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Explore the platform's architecture with interactive C4 diagrams. Understand the
|
|||
**Dive into the architecture →**
|
||||
{{% /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.
|
||||
|
||||
**Start documenting →**
|
||||
|
|
@ -73,7 +73,7 @@ Access the previous version of our documentation including historical project in
|
|||
|
||||
## 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
|
||||
- 🏗️ Explore [Platform Components](/docs/architecture/) and their interactions
|
||||
|
|
|
|||
|
|
@ -6,11 +6,11 @@ description: >
|
|||
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
|
||||
- Creating architecture diagrams with LikeC4
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: "Local Development"
|
|||
linkTitle: "Local Development"
|
||||
weight: 20
|
||||
description: >
|
||||
Set up your local environment and learn the documentor workflow.
|
||||
Set up your local environment and learn the technicalWriter workflow.
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
|
@ -193,7 +193,7 @@ For comprehensive testing, including link checking:
|
|||
task test
|
||||
```
|
||||
|
||||
## Tips for Documentors
|
||||
## Tips for Technical Writers
|
||||
|
||||
1. **Write in present tense** - "The system processes..." not "The system will process..."
|
||||
2. **Use code blocks** with syntax highlighting
|
||||
|
|
|
|||
|
|
@ -166,7 +166,7 @@ Documentation is now accessible:
|
|||
|
||||
### 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`
|
||||
3. **Commit and push** to Git repository
|
||||
4. **GitHub Actions triggered** on push to main
|
||||
|
|
@ -336,4 +336,4 @@ The deployment process is automated and reliable:
|
|||
✅ **Kubernetes orchestration** - Reliable, scalable platform
|
||||
✅ **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! 🚀
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: "Quick Reference"
|
|||
linkTitle: "Quick Reference"
|
||||
weight: 60
|
||||
description: >
|
||||
Cheat sheet for common documentor tasks.
|
||||
Cheat sheet for common technicalWriter tasks.
|
||||
---
|
||||
|
||||
## Common Commands
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ This folder contains LikeC4 architecture models that document the documentation
|
|||
|
||||
## Purpose
|
||||
|
||||
These models help new **Documentors** understand:
|
||||
These models help new **Technical Writers** understand:
|
||||
|
||||
- How the documentation platform works
|
||||
- The local development workflow
|
||||
|
|
@ -24,7 +24,7 @@ High-level view of the entire documentation platform, showing all major componen
|
|||
|
||||
### 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
|
||||
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ specification {
|
|||
model {
|
||||
|
||||
// === Personas ===
|
||||
documentor = person 'Documentor' {
|
||||
technicalWriter = person 'Technical Writer' {
|
||||
description 'Content creator and maintainer of the developer platform documentation'
|
||||
technology 'Hugo, Markdown, LikeC4'
|
||||
}
|
||||
|
|
@ -151,16 +151,16 @@ deploymentEnv = system 'Deployment Environment' {
|
|||
}
|
||||
}
|
||||
|
||||
// === Relationships: Documentor Workflow ===
|
||||
documentor -> contentRepo.contentPages 'writes documentation' {
|
||||
// === Relationships: Technical Writer Workflow ===
|
||||
technicalWriter -> contentRepo.contentPages 'writes documentation' {
|
||||
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'
|
||||
}
|
||||
|
||||
documentor -> taskfile 'executes local tasks' {
|
||||
technicalWriter -> taskfile 'executes local tasks' {
|
||||
description 'task serve, task build, task test'
|
||||
}
|
||||
|
||||
|
|
@ -244,7 +244,7 @@ deploymentEnv.k8sCluster.docDeployment -> deploymentEnv.k8sCluster.docService 'e
|
|||
description 'Port 80'
|
||||
}
|
||||
|
||||
documentor -> deploymentEnv.k8sCluster.docService 'views published docs' {
|
||||
technicalWriter -> deploymentEnv.k8sCluster.docService 'views published docs' {
|
||||
description 'HTTPS access to live documentation'
|
||||
}
|
||||
|
||||
|
|
@ -256,11 +256,11 @@ views {
|
|||
|
||||
view overview of docPlatform {
|
||||
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 *
|
||||
|
||||
style documentor {
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform {
|
||||
|
|
@ -270,9 +270,9 @@ views {
|
|||
|
||||
view localDevelopment of docPlatform {
|
||||
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.contentRepo -> *
|
||||
include docPlatform.hugoSite
|
||||
|
|
@ -280,7 +280,7 @@ views {
|
|||
include docPlatform.taskfile
|
||||
include docPlatform.devServer
|
||||
|
||||
style documentor {
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform.taskfile {
|
||||
|
|
@ -317,7 +317,7 @@ views {
|
|||
include deploymentEnv
|
||||
include deploymentEnv.edgeConnect
|
||||
include deploymentEnv.k8sCluster -> *
|
||||
include documentor
|
||||
include technicalWriter
|
||||
|
||||
style deploymentEnv {
|
||||
color muted
|
||||
|
|
@ -328,10 +328,10 @@ views {
|
|||
}
|
||||
|
||||
view fullWorkflow {
|
||||
title 'Complete Documentor Workflow'
|
||||
title 'Complete Technical Writer Workflow'
|
||||
description 'End-to-end view from content creation to published documentation'
|
||||
|
||||
include documentor
|
||||
include technicalWriter
|
||||
include docPlatform.contentRepo
|
||||
include docPlatform.taskfile
|
||||
include cicdPipeline.githubActions
|
||||
|
|
@ -339,7 +339,7 @@ views {
|
|||
include deploymentEnv.edgeConnect
|
||||
include deploymentEnv.k8sCluster
|
||||
|
||||
style documentor {
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform.taskfile {
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
model {
|
||||
|
||||
// === Personas ===
|
||||
documentor = person 'Documentor' {
|
||||
technicalWriter = person 'Technical Writer' {
|
||||
description 'Content creator and maintainer of the developer platform documentation'
|
||||
technology 'Hugo, Markdown, LikeC4'
|
||||
}
|
||||
|
|
@ -116,16 +116,16 @@ deploymentEnv = system 'Deployment Environment' {
|
|||
}
|
||||
}
|
||||
|
||||
// === Relationships: Documentor Workflow ===
|
||||
documentor -> contentRepo.contentPages 'writes documentation' {
|
||||
// === Relationships: Technical Writer Workflow ===
|
||||
technicalWriter -> contentRepo.contentPages 'writes documentation' {
|
||||
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'
|
||||
}
|
||||
|
||||
documentor -> taskfile 'executes local tasks' {
|
||||
technicalWriter -> taskfile 'executes local tasks' {
|
||||
description 'task serve, task build, task test'
|
||||
}
|
||||
|
||||
|
|
@ -209,7 +209,7 @@ deploymentEnv.k8sCluster.docDeployment -> deploymentEnv.k8sCluster.docService 'e
|
|||
description 'Port 80'
|
||||
}
|
||||
|
||||
documentor -> deploymentEnv.k8sCluster.docService 'views published docs' {
|
||||
technicalWriter -> deploymentEnv.k8sCluster.docService 'views published docs' {
|
||||
description 'HTTPS access to live documentation'
|
||||
}
|
||||
|
||||
|
|
@ -221,11 +221,11 @@ views {
|
|||
|
||||
view overview of docPlatform {
|
||||
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 *
|
||||
|
||||
style documentor {
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform {
|
||||
|
|
@ -235,9 +235,9 @@ views {
|
|||
|
||||
view localDevelopment of docPlatform {
|
||||
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.contentRepo -> *
|
||||
include docPlatform.hugoSite
|
||||
|
|
@ -245,7 +245,7 @@ views {
|
|||
include docPlatform.taskfile
|
||||
include docPlatform.devServer
|
||||
|
||||
style documentor {
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform.taskfile {
|
||||
|
|
@ -282,7 +282,7 @@ views {
|
|||
include deploymentEnv
|
||||
include deploymentEnv.edgeConnect
|
||||
include deploymentEnv.k8sCluster -> *
|
||||
include documentor
|
||||
include technicalWriter
|
||||
|
||||
style deploymentEnv {
|
||||
color muted
|
||||
|
|
@ -293,10 +293,10 @@ views {
|
|||
}
|
||||
|
||||
view fullWorkflow {
|
||||
title 'Complete Documentor Workflow'
|
||||
title 'Complete Technical Writer Workflow'
|
||||
description 'End-to-end view from content creation to published documentation'
|
||||
|
||||
include documentor
|
||||
include technicalWriter
|
||||
include docPlatform.contentRepo
|
||||
include docPlatform.taskfile
|
||||
include cicdPipeline.githubActions
|
||||
|
|
@ -304,7 +304,7 @@ views {
|
|||
include deploymentEnv.edgeConnect
|
||||
include deploymentEnv.k8sCluster
|
||||
|
||||
style documentor {
|
||||
style technicalWriter {
|
||||
color green
|
||||
}
|
||||
style docPlatform.taskfile {
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
Loading…
Add table
Add a link
Reference in a new issue