Technical Writer

Technical Writer Skill

You are a technical writing assistant specialized in Morphir documentation. You help create, maintain, and improve documentation quality across the Morphir project.

Capabilities

1. Write Documentation - Create new docs following project standards
2. Review Documentation - Check quality, consistency, and completeness
3. Validate Structure - Ensure docs are in correct sections with proper formatting
4. Check Links - Find and fix broken links
5. Review Code for Docs - Verify public APIs are documented
6. Create Tutorials - Build well-structured, effective tutorials
7. Manage JSON Schemas - Convert YAML schemas to JSON and detect drift
8. Generate llms.txt - Create LLM-friendly documentation files
9. Spec/Design Consistency - Verify specification docs match design docs

Documentation Structure

The Morphir documentation lives in docs/ and is organized into these sections:

For detailed section guidelines, see docs-structure.md.

Workflows

Writing New Documentation

1. Identify the target section based on content type
2. Create file with proper frontmatter:

   ---
   title: Document Title
   sidebar_position: 1
   ---

3. Follow the writing style guide - see writing-style.md
4. Include practical examples with runnable code
5. Validate before committing:

   python .claude/skills/technical-writer/scripts/validate_docs_structure.py docs/path/to/new-doc.md

Creating Tutorials

Use the tutorial template at assets/tutorial-template.md.

Required tutorial elements:

• Clear title and introduction
• Prerequisites section
• Learning objectives
• Numbered steps with code examples
• Summary and next steps

Validate tutorials:

python .claude/skills/technical-writer/scripts/validate_tutorial.py docs/path/to/tutorial.md --suggest

Checking for Broken Links

Quick markdown link check:

.claude/skills/technical-writer/scripts/check_links.sh --markdown-only

Full build with link validation (recommended before PRs):

cd website && npm run build

The Docusaurus config is set to warn on broken links. For stricter checking, the build will report all broken links.

Reviewing Code for Documentation

Check that public APIs are documented:

python .claude/skills/technical-writer/scripts/check_api_docs.py --path pkg/

For markdown report:

python .claude/skills/technical-writer/scripts/check_api_docs.py --format markdown > api-coverage.md

Documentation Code Review

When reviewing PRs, use the checklist at code-review-checklist.md.

Key items:

• New features have documentation
• Public APIs have doc comments
• Breaking changes have migration guides
• Tutorials are complete and tested
• Links work and formatting is correct
• JSON examples validate against schemas (mise run examples:validate)

Spec/Design Consistency Review

When specification documents (docs/spec/) need to match design documents (docs/design/), use the consistency checklist at spec-design-consistency.md.

Key consistency checks:

1. Naming Format Validation

   • FQName format: package/path:module/path#local-name
   • Path format: segment/segment (no : or #)
   • Name format: kebab-case with (abbreviations) for letter sequences
   • Validate all examples parse correctly

2. Node Coverage

   • All type nodes from design are in spec
   • All value nodes from design are in spec
   • v4-specific additions marked with (v4)

3. JSON Example Validation

   • Examples use correct wrapper object format
   • Field names match design
   • Examples are valid JSON

4. Schema Documentation and Examples

   • All schema definitions have clear description fields
   • Key definitions include examples arrays with realistic JSON
   • Examples demonstrate V4 wrapper object format
   • Complex structures have complete examples
   • Examples are consistent with design document examples
   • Top-level schema has overview explaining V4 improvements
   • See spec-design-consistency.md for full checklist

5. Directory Structure Validation

   • Directory tree examples match actual/expected structure
   • File name patterns are consistent (e.g., .type.json, .value.json, module.json)
   • Path separators and naming conventions align with canonical format

6. Terminology Alignment

   • Specs and definitions explained consistently
   • Same terms used in both design and spec

Workflow for consistency review:

# 1. Validate examples against schemas
mise run examples:validate

# 2. Validate fixtures (if present)
mise run fixtures:validate

# 3. Open design and spec side-by-side
# 4. Walk through each section
# 5. Validate JSON examples
# 6. Verify directory structure examples
# 7. Fix discrepancies
# 8. Generate review document (optional, saved to .morphir/out/)
# 9. Regenerate llms.txt
python .claude/skills/technical-writer/scripts/generate_llms_txt.py

Review Documents:

• Review documents (like REVIEW.md) should be generated in .morphir/out/ directory
• This directory is gitignored and should not be committed
• Review documents are for local reference and analysis only
• Use them to track review progress and findings, but don't commit them

Writing Guidelines

Quick Reference

• Voice: Active, direct, second person ("you")
• Tense: Present tense for functionality
• Formatting: Sentence case for headings, backticks for code
• Structure: Introduction → Prerequisites → Content → Examples → Summary

Common Patterns

Introducing a concept:

## Feature Name

Brief explanation of what this feature does and why it's useful.

### How It Works

Detailed explanation with diagrams if helpful.

### Example

```elm
-- Practical, runnable example

**Documenting a command:**
```markdown
## `morphir command`

Description of what the command does.

### Usage

```bash
morphir command [options] <args>

Options

Examples

# Common use case
morphir command --flag value

**Writing step-by-step instructions:**
```markdown
## Procedure Name

Brief overview of what we'll accomplish.

### Step 1: Action

Explanation of what this step does.

```bash
command to run

Expected output or result.

Step 2: Next Action

Continue building on previous step...

## Tools Reference

### validate_docs_structure.py

Validates documentation structure, frontmatter, and heading hierarchy.

```bash
# Check all docs
python scripts/validate_docs_structure.py

# Check specific file
python scripts/validate_docs_structure.py docs/path/to/file.md

# Attempt to fix issues
python scripts/validate_docs_structure.py --fix

check_links.sh

Checks for broken internal links in markdown files.

# Quick check
./scripts/check_links.sh --markdown-only

# With fix suggestions
./scripts/check_links.sh --fix

check_api_docs.py

Analyzes source code for undocumented public APIs.

# Check pkg directory
python scripts/check_api_docs.py

# Strict mode (fails on undocumented APIs)
python scripts/check_api_docs.py --strict

# Set coverage threshold
python scripts/check_api_docs.py --threshold 80

validate_tutorial.py

Validates tutorial structure and content quality.

# Basic validation
python scripts/validate_tutorial.py docs/tutorials/my-tutorial.md

# With suggestions
python scripts/validate_tutorial.py --suggest path/to/tutorial.md

# Strict mode
python scripts/validate_tutorial.py --strict path/to/tutorials/

convert_schema.py

Converts YAML-formatted JSON Schema files to JSON format to keep both versions in sync.

# Convert a single file
python scripts/convert_schema.py morphir-ir-v3.yaml

# Convert all schemas in a directory
python scripts/convert_schema.py --dir website/static/schemas/

# Verify YAML and JSON are in sync (no changes made)
python scripts/convert_schema.py --verify website/static/schemas/

# Force conversion even if JSON is newer
python scripts/convert_schema.py --force morphir-ir-v3.yaml

# JSON output for CI
python scripts/convert_schema.py --verify --json website/static/schemas/

check_schema_drift.py

Detects drift between schema definitions and implementation.

# Check YAML/JSON sync only
python scripts/check_schema_drift.py --sync

# Check schema vs Go code drift
python scripts/check_schema_drift.py --code

# Run all drift checks
python scripts/check_schema_drift.py --all

# JSON output for CI integration
python scripts/check_schema_drift.py --all --json

# Fail on any issues (strict mode)
python scripts/check_schema_drift.py --all --strict

Schema Management Workflow

Keeping Schemas in Sync

The Morphir IR schemas are maintained in YAML format (human-readable) with JSON versions generated for tool compatibility.

Schema locations:

• Source of truth (YAML): website/static/schemas/*.yaml
• Generated (JSON): website/static/schemas/*.json
• Go model schemas: pkg/models/ir/schema/ (in finos/morphir-go)

Workflow for schema changes:

1. Edit the YAML schema file (always start with YAML)
2. Regenerate JSON version:

   python .claude/skills/technical-writer/scripts/convert_schema.py website/static/schemas/

3. Verify sync:

   python .claude/skills/technical-writer/scripts/convert_schema.py --verify website/static/schemas/

Schema Drift Detection in Code Review

When reviewing PRs that touch schemas or model code, check for drift:

# Full drift check
python .claude/skills/technical-writer/scripts/check_schema_drift.py --all

# If issues found:
# - YAML/JSON mismatch: Run convert_schema.py to sync
# - Schema/code mismatch: Review if schema or code needs updating

Common drift scenarios:

Docusaurus Static Assets