josavicentevw AI README Authoring Guide
Use this guide when prompting an AI to draft or refresh a README that follows the SOLO README schema. The goal is a concise, operations-ready document that orients newcomers and on-call engineers without needing tribal knowledge.
Schema to Follow (in order)
- Title & Quick Descriptor: Service name plus a one-line value statement; badges only if already available.
- TL;DR / Overview: 3–5 sentences on what the service does, who consumes it, and the core business flow it supports.
- Key Responsibilities & Use Cases: Bullet the primary jobs-to-be-done and critical paths; call out constraints or SLAs.
- Interfaces: REST/gRPC topics, async queues, cron jobs. Link Swagger/OpenAPI, protobuf specs, and message contracts.
- Architecture: High-level system/context view and deployment topology only (Mermaid if available); keep arrows simple and directional; avoid per-endpoint or per-notification flow diagrams.
- Configuration & Secrets: Required env vars, config sources, feature flags, secrets management location (no secrets inline).
- Local Development: Prereqs, how to start dependencies, how to run the app, common bootstrap commands, sample data.
- Testing: How to run tests (unit/integration/e2e), coverage commands, and notable fixtures or contracts.
- Security & Compliance: AuthN/Z expectations, required roles/scopes, data handling/PII notes, threat surfaces.
- Observability: Health/metrics/traces/logging endpoints, dashboards, alerts, and log conventions.
- Operations & Deployments: CI/CD entry points, release cadence, runtime profiles, rollback/recovery notes, runbooks.
- Troubleshooting: Frequent failure modes with quick checks.
- References & Ownership: Links to ADRs, RFCs, upstream docs, and the owning team/contact channel.
Content Rules
- Write for engineers onboarding or on-call; keep paragraphs short and use bullets when possible.
- Prefer links to canonical sources over duplicating details; keep commands copy-pastable.
- Use tables for env vars/config when the list is long; avoid placeholder secrets.
- Call out what is required vs. optional; include defaults where safe.
- Keep diagrams minimal: system/context and deployment only; avoid component-level or sequence/notification flows unless the user explicitly asks for them; ensure arrows read left-to-right or top-down to reduce ambiguity.
Ask the User Before Drafting
Collect these inputs (links preferred) so the AI can populate the schema accurately:
- Current service name, one-line elevator pitch, and primary business flow it supports.
- API surface: Swagger/OpenAPI URL, gRPC/proto repo paths, and any message/queue contracts.
- Architecture references: existing system/context or deployment diagrams (Mermaid/PlantUML/images) and a short component rundown; confirm if additional diagrams are desired.
- Data and storage: main entities, schemas/migrations, and where canonical definitions live.
- Configuration: required env vars with defaults, feature flags, and where secrets are stored/loaded.
- Local dev: prerequisites, how to start dependencies (Docker Compose, mocks), and seed data locations.
- Testing: commands for unit/integration/e2e, notable fixtures, and coverage expectations.
- Security: required roles/scopes/permissions, auth mechanisms, and PII/data handling constraints.
- Observability: health endpoints, metrics/traces/logging conventions, dashboard/alert links.
- Operations: deployment pipeline entry points, runtime profiles, rollback steps, runbooks, and SLO/SLA targets.
- Ownership and support: responsible team, contact channel, and where to file incidents or tickets.
Prompt Template (suggested)
You are documenting the README for <service>. Follow the SOLO README schema below and keep it concise and actionable.
- Title & Quick Descriptor
- TL;DR / Overview
- Key Responsibilities & Use Cases
- Interfaces (REST/gRPC/queues/cron) with links
- Architecture (system/context + deployment only; keep arrows simple; no per-endpoint flows)
- Data Model (entities + storage)
- Configuration & Secrets
- Local Development
- Testing
- Security & Compliance
- Observability
- Operations & Deployments
- Troubleshooting
- References & Ownership
Use the provided links and details:
<paste user-provided answers/links here>