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 (fastest - Hugo only)
task test:hugo

# Or run full tests (includes LikeC4 validation)
task test

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

Documentation Structure

content/en/
├── _index.md              # Homepage
├── docs/
│   ├── _index.md          # Docs landing page
│   ├── edgeconnect/       # Edge Connect documentation
│   ├── edp/               # EDP platform documentation
│   └── governance/        # Governance documentation
├── docs-old/              # Legacy documentation (archived)
└── blog/                  # Blog posts
    ├── 20250401_review.md
    ├── 20251027_important_links.md
    └── 240823-archsession.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"

Using LikeC4 with AI Agents (MCP Server)

The LikeC4 Model Context Protocol (MCP) server allows AI agents to query and navigate your architecture models interactively.

Configuring AI Agents

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "likec4": {
      "type": "sse",
      "url": "http://localhost:33335/mcp"
    }
  }
}

This configuration gives GitHub Copilot and other MCP-compatible AI agents access to LikeC4 tools for querying your architecture models.

Starting the MCP Server

Start the LikeC4 MCP server locally:

# in the project root of the documentation repo
npx likec4 mcp resources/edp-likec4 --http

The server runs on http://localhost:33335/mcp by default.

Querying Architecture Models

Once connected, you can ask the AI agent questions like:

• "In which model file is the resource edp.garm specified?"

  • Returns: resources/edp-likec4/models/containers/garm.c4

• "Show me all views that include the forgejo element"

  • Lists all views containing the forgejo element

• "What relationships does edp.garm have?"

  • Shows incoming and outgoing relationships

• "List all elements in the architecture project"

  • Provides a complete overview of elements

Available MCP Tools

The LikeC4 MCP server provides these tools to AI agents:

• list-projects - List all LikeC4 projects
• search-element - Search elements by id/title/kind/tags
• read-element - Get detailed element information
• read-view - Get view details (nodes/edges)
• read-deployment - Get deployment node information
• find-relationships - Find relationships between elements
• read-project-summary - Get project overview

Use Cases

Finding definitions:

"Where is edp.forgejo defined?"

Understanding relationships:

"What components does edp.garm contain?"

Exploring views:

"Which views show the deployment architecture?"

Documentation validation:

"Check if all elements in the forgejoGarmInteraction view are documented"

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 (includes LikeC4)
task test:hugo	Run Hugo-only tests (fastest)
task test:full	All tests + link checking

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! 📝✨