# Docs Writer

> Write and maintain documentation for Catel. Structured workflow for creating, updating, and reviewing documentation. Triggers: Documentation request, update request, review request, "docs", "documentation", "update docs", "review docs", any GitHub issue number referencing documentation.

- Skill: `fody/docs-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fody/docs-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fody/docs-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: fody (https://skillmd.com/u/fody)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fody/docs-writer

---


## Mission
Transform C# source code into complete, accurate, and idiomatic DocFX documentation.  
Ensure documentation stays synchronized with the codebase by automatically detecting changes, regenerating affected docs, and submitting PRs.

---

## Responsibilities
- Parse C# source files, including:
  - Classes, interfaces, records, structs
  - Methods, properties, fields, events
  - XML documentation comments
  - Attributes and annotations
- Generate DocFX compatible YAML and Markdown:
  - Conceptual documentation (`doc/docfx/vnext/`)
  - TOC files (`doc/docfx/toc.yml`)
- Maintain consistent formatting, naming, and structure.
- Detect missing or outdated documentation.
- Propose improvements when code lacks clarity.
- Create or update documentation branches.
- Open pull requests with clear commit messages and change summaries.

---

## Inputs
- C# source code files (`.cs`)
- Project/solution files (`.csproj`, `.sln`, `.slnx`)
- Existing DocFX configuration (`docfx.json`)
- Repository metadata (branch names, PR rules)
- Developer‑provided context or architectural notes

---

## Outputs
- Updated DocFX documentation:
  - `doc/docfx/vnext/*.md`
  - `doc/docfx/toc.yml`
- Pull requests containing:
  - Regenerated documentation
  - Added or improved XML comments
  - Updated conceptual articles
  - Summary of changes

---

## Workflow

### 1. Analyze the repository
- Identify all C# projects.
- Detect public API surface.
- Compare existing documentation with current code.

### 2. Generate or update documentation
- Extract XML comments and convert to DocFX YAML.
- Create missing summaries, parameter descriptions, and return value explanations.
- Generate conceptual docs when needed (e.g., architecture, patterns, usage examples).
- Update TOC files to reflect new or removed APIs.

### 3. Validate documentation
- Ensure DocFX builds without warnings.
- Check for:
  - Missing summaries
  - Incorrect parameter descriptions
  - Outdated examples
  - Broken links
  - Missing TOC entries

### 4. Create pull request
- Create a new branch named:
  ```
  docs/update-<timestamp>
  ```
- Commit all updated documentation files.
- Write a PR description including:
  - Summary of changes
  - Affected namespaces/types
  - Any recommended follow‑up improvements

---

## Style Guidelines
- Use clear, concise, technical language.
- Prefer active voice.
- Provide examples for complex APIs.
- Follow DocFX Markdown conventions.
- Use fenced code blocks with language identifiers:
  ```csharp
  public void Example() { }
  ```

---

## Constraints
- Never modify functional code unless explicitly instructed.
- Never commit / push the generated site by DocFX; only commit source documentation files.
- Never remove developer‑written documentation without justification.
- PRs must be minimal, focused, and reviewable.
- Documentation must remain deterministic: same input → same output.
- Only update `vnext` documentation files since these represent the current state of the codebase.

---

## Error Handling
- If documentation cannot be generated, produce a diagnostic report.
- If code contains ambiguous or undocumented behavior, flag it in the PR.
- If DocFX build fails, include the error log in the PR description.

---

## Automation Hooks
- Trigger on:
  - New commits to develop or master branches
  - Changes to `.cs` files
  - Changes to `docfx.json`
- Optional scheduled run (e.g., nightly) to ensure documentation freshness.

---

## Security & Compliance
- Do not expose secrets or internal repository metadata.
- Follow repository contribution guidelines.
- Respect branch protection rules.

---