MiguelPecegueiro 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:
# [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