website-and-documentation/doc/README-technical-writer.md

Technical Writer Guide

Welcome! This guide helps you contribute to the IPCEI-CIS Developer Framework documentation.

Prerequisites

• Basic knowledge of Markdown
• Git installed
• Either Devbox (recommended) or manual tool installation

Quick Start

1. Clone and Setup

# Clone the repository
git clone <repository-url>
cd ipceicis-developerframework

# Install dependencies
task deps:install

# If using Devbox
devbox shell

2. Start Development Server

task serve

Open your browser at http://localhost:1313 - changes appear instantly!

3. Create Content

Create a new page:

# Example: Add a new guide
vim content/en/docs/your-topic/_index.md

Add frontmatter:

---
title: "Your Topic"
linkTitle: "Your Topic"
weight: 10
description: >
  Brief description of your topic.
---

Your content here...

4. Test and Commit

# Run tests
task test:quick

# Commit your changes
git add .
git commit -m "docs: Add guide for X"
git push

Documentation Structure

content/en/
├── _index.md              # Homepage
├── docs/
│   ├── architecture/      # Architecture documentation
│   │   └── highlevelarch.md
│   ├── documentation/     # Documentation guides
│   │   ├── local-development.md
│   │   ├── testing.md
│   │   └── cicd.md
│   ├── decisions/         # ADRs (Architecture Decision Records)
│   └── v1/               # Legacy documentation
└── blog/                 # Blog posts
    └── 20250401_review.md

Writing Documentation

Markdown Basics

# Heading 1
## Heading 2
### Heading 3

**Bold text**
*Italic text*

- Bullet list
- Item 2

1. Numbered list
2. Item 2

[Link text](https://example.com)

`inline code`

\`\`\`bash
# Code block
echo "Hello"
\`\`\`

Using Shortcodes

Alerts

{{< alert title="Note" >}}
Important information here
{{< /alert >}}

{{< alert title="Warning" color="warning" >}}
Warning message
{{< /alert >}}

Code Tabs

{{< tabpane >}}
{{< tab header="Bash" >}}
\`\`\`bash
echo "Hello"
\`\`\`
{{< /tab >}}
{{< tab header="Python" >}}
\`\`\`python
print("Hello")
\`\`\`
{{< /tab >}}
{{< /tabpane >}}

Creating Architecture Diagrams

1. Edit LikeC4 Models

Navigate to the appropriate project:

• resources/edp-likec4/ - Platform architecture
• resources/doc-likec4/ - Documentation platform architecture

Create or edit .c4 files:

specification {
  element person
  element system
}

model {
  user = person 'User' {
    description 'End user of the platform'
  }
  
  platform = system 'Platform' {
    description 'The EDP platform'
  }
  
  user -> platform 'uses'
}

views {
  view overview {
    title "System Overview"
    
    include user
    include platform
    
    autoLayout TopBottom
  }
}

2. Generate Webcomponent

task likec4:generate

3. Embed in Documentation

{{< likec4-view view="overview" project="architecture" title="System Overview" >}}

Parameters:

• view - View ID from your .c4 file
• project - "architecture" or "documentation-platform"
• title - Custom header text (optional)

4. Find Available Views

# List all view IDs
grep -r "^view " resources/edp-likec4/ --include="*.c4"

Available Tasks

View all tasks:

task --list

Development Tasks

Task	Description
task serve	Start dev server with hot reload
task build	Build production site
task clean	Remove build artifacts
task test	Run all tests (build, markdown, HTML, links)
task test:quick	Run quick tests (build, markdown)

LikeC4 Tasks

Task	Description
task likec4:generate	Generate webcomponents from .c4 files
task likec4:validate	Validate LikeC4 syntax
task likec4:update	Update LikeC4 to latest version

Dependency Tasks

Task	Description
task deps:install	Install all dependencies
task deps:update	Update dependencies

Testing

Quick Test (Recommended)

Before committing:

task test:quick

Validates:

• Hugo build succeeds
• Markdown syntax is correct
• LikeC4 models are valid

Full Test

Includes link checking:

task test

Note: Link checking can be slow. Use test:quick during development.

Best Practices

Writing Style

✅ Do:

• Write in present tense: "The system processes..."
• Use code blocks with syntax highlighting
• Keep sections concise (3-5 paragraphs max)
• Add diagrams for complex concepts
• Use bullet points for lists
• Test locally before committing

❌ Don't:

• Use future tense: "The system will process..."
• Write long paragraphs (split into sections)
• Forget to add descriptions in frontmatter
• Commit without testing

Frontmatter

Always include:

---
title: "Page Title"          # Full title
linkTitle: "Short Title"     # Used in navigation
weight: 10                   # Order in menu (lower = higher)
description: >               # Used in SEO and cards
  Brief description of the page content.
---

Optional:

---
date: 2025-01-15            # Publication date (for blog posts)
author: "Your Name"         # Author name
categories: ["Category"]    # Categories
tags: ["tag1", "tag2"]      # Tags
---

File Naming

• Use lowercase
• Use hyphens, not underscores: my-guide.md not my_guide.md
• Main page in a section: _index.md
• Single page: page-name.md

Images

Place images in the same folder as your markdown file:

docs/my-guide/
├── _index.md
├── screenshot.png
└── diagram.svg

Reference them:

![Alt text](screenshot.png)

Common Issues

Port 1313 already in use

# Find and kill the process
lsof -ti:1313 | xargs kill -9

Build errors

# Clean and rebuild
task clean
task build:dev

Hugo not found (when not using Devbox)

# Make sure you're in devbox shell
devbox shell

# Or install Hugo manually
# See: https://gohugo.io/installation/

LikeC4 validation fails

# Validate with detailed output
cd resources/edp-likec4
npx likec4 validate --verbose

# Ignore layout drift (common, not critical)
npx likec4 validate --ignore-layout

Git Workflow

Create a Branch

git checkout -b feature/my-new-guide

Commit Changes

# Stage your changes
git add content/en/docs/my-guide/

# Commit with clear message
git commit -m "docs: Add guide for X feature"

Commit Message Convention

Format: <type>: <description>

Types:

• docs: - Documentation changes
• feat: - New feature or content
• fix: - Bug fix or correction
• chore: - Maintenance tasks
• style: - CSS/styling changes

Examples:

docs: Add installation guide for Windows users
feat: Add interactive architecture diagram for OTC deployment
fix: Correct typo in API documentation
chore: Update LikeC4 to version 1.43.0

Push and Create PR

# Push your branch
git push origin feature/my-new-guide

# Create Pull Request on Forgejo/GitHub

Getting Help

• Full Documentation: See /content/en/docs/documentation/
• LikeC4 Documentation: https://likec4.dev/
• Hugo Documentation: https://gohugo.io/documentation/
• Docsy Theme: https://www.docsy.dev/docs/

Next Steps

1. Read the Local Development Guide
2. Explore Architecture Documentation
3. Check Testing Guide
4. Learn about CI/CD Pipeline

Happy documenting! 📝✨