# Write Docu

> Write complete technical documentation for the current project or codebase. Use when the user says "write-docu", "write documentation", "document this project", or "generate docs for this repo". Analyses the full codebase, creates or updates markdown files in the docs/ folder, and produces documentation detailed enough for someone picking up the project for the first time to understand how it works, how it is structured, and how to implement a feature or hotfix.

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

---


# Write Documentation

Analyse the current codebase and write complete technical documentation in the
`docs/` folder.

## GoConnection context

- Stack: .NET 8/10 ASP.NET Core, Razor Pages, Worker Services; Python Flask (GC_Tools only)
- All apps have an IT-SA reference code — include it in the document header if known
- Confluence holds the system register (identity, integrations, security posture, links)
- The repo owns all technical implementation detail — that is what this skill produces
- ISO 9001 and ISO 27001 in scope — document security-relevant behaviour explicitly

---

## Workflow

### 1. Read first, write second

Before writing anything:
- Read every file in `docs/` — if documentation exists, use it as a starting point
- Read the entry point (Program.cs, app.py, etc.) in full
- Read the dependency manifest
- Read the deploy/CI config
- Read at least one end-to-end flow through the application

Do not write documentation from filenames and class names alone. Read the actual code.

### 2. Decide on structure

**Single file** — use when the app is focused enough that one document covers it without
becoming unwieldy (roughly: one main responsibility, under ~15 significant source files).

**Parent + child files** — use when the app has multiple distinct subsystems, clients,
or integration layers. Parent file is an overview and table of contents; child files
go into specifics.

Name child files descriptively: `docs/endesa-outbound.md`, `docs/database-schema.md`,
`docs/deployment.md` — not `docs/part1.md`.

### 3. Write the documentation

Every document must include this header:

```markdown
# [Product / Service / Feature Name]

**IT-SA reference:** [e.g. IT-SA-19, or N/A]  
**Document version:** [e.g. 1.0]  
**Last updated:** [YYYY-MM-DD]  
```

Every document must include a table of contents if it exceeds ~100 lines.

Cover these sections as applicable:

**Overview** — what the app does in plain language. One paragraph. No filler.

**Architecture** — how it is structured. Key classes, layers, patterns used.
If there is a data flow worth documenting, describe it.

**Database** — tables, schemas, key columns, relationships. Include the schema
prefix (e.g. `Clientes.edp.*`). Note any linked server dependencies.

**Configuration** — what config keys exist, where they come from (Key Vault vs
appsettings), what they control.

**Integrations** — every external system the app talks to. What protocol, what
auth, what data flows in each direction.

**Deployment** — how it is deployed, where it runs, how to deploy manually if needed.
Note the IIS app pool name, the deploy path, any Windows Service name.

**Running locally** — how to set it up from scratch. Dependencies, config needed,
commands to run.

**Common operations** — things someone will need to do repeatedly: manual triggers,
reprocessing failed records, adding a new client or campaign, etc.

**Known issues and limitations** — anything that is incomplete, has known bugs,
or requires careful handling. Do not hide this.

---

## Writing style

Write in plain technical English. No marketing language, no AI mannerisms.

**Never use:**
- Em dashes (—) or en dashes (–) as sentence connectors — use a comma, period, or rewrite
- Filler openers: "This document...", "This service...", "It is worth noting that..."
- Weasel amplifiers: "seamlessly", "robust", "powerful", "leverages", "facilitates",
  "enables", "streamlined", "comprehensive", "holistic"
- Passive voice where active is possible
- Hedging non-statements: "it should be noted", "importantly", "it is important to note"
- Noun stacks dressed as explanations: "end-to-end solution", "holistic approach"

**Always prefer:**
- Short declarative sentences
- Active voice: "The service reads from X and writes to Y"
- Concrete over abstract: say what it does, not what it "enables"
- If a word can be cut without losing meaning, cut it

---

## Rules

- Always write to `docs/` — never to the project root or other locations
- Always check for existing documentation before writing — update, do not replace blindly
- Increment the document version when updating existing docs
- Do not document implementation details that are obvious from reading the code — document
  intent, decisions, and non-obvious behaviour
- Do not modify source files
- If the codebase is too large to document fully in one session, document the most
  critical subsystems first and note what remains in a `docs/TODO.md`