# 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 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 (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/ │ ├── 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 (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: ```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: `: ` 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! 📝✨