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

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

# Install dependencies
task deps:install

# If using Devbox
devbox shell
```

### 2. Start Development Server

```bash
task serve
```

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

### 3. Create Content

Create a new page:

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

Add frontmatter:

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

Your content here...
```

### 4. Test and Commit

```bash
# 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

```markdown
# 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

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

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

#### Code Tabs

```markdown
{{< 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:

```likec4
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

```bash
task likec4:generate
```

### 3. Embed in Documentation

```markdown
{{< 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

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

## Available Tasks

View all tasks:

```bash
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:

```bash
task test:quick
```

Validates:
- Hugo build succeeds
- Markdown syntax is correct
- LikeC4 models are valid

### Full Test

Includes link checking:

```bash
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:

```yaml
---
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:

```yaml
---
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:

```markdown
![Alt text](screenshot.png)
```

## Common Issues

### Port 1313 already in use

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

### Build errors

```bash
# Clean and rebuild
task clean
task build:dev
```

### Hugo not found (when not using Devbox)

```bash
# Make sure you're in devbox shell
devbox shell

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

### LikeC4 validation fails

```bash
# 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

```bash
git checkout -b feature/my-new-guide
```

### Commit Changes

```bash
# 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

```bash
# 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](./content/en/docs/documentation/local-development.md)
2. Explore [Architecture Documentation](./content/en/docs/architecture/)
3. Check [Testing Guide](./content/en/docs/documentation/testing.md)
4. Learn about [CI/CD Pipeline](./content/en/docs/documentation/cicd.md)

Happy documenting! 📝✨