version: "1.0.0" name: client-facing-docs description: Writing client-facing technical documentation — architecture documents, proposals, project presentations — in plain language, jargon-free, with honest numbers and explicit pragmatic engineering principles. Use whenever the material will be read by a client or non-technical stakeholder - architecture doc, kickoff presentation, proposal, delivery report or closing email.

Client-facing documentation

A document for a client is not a technical document with a nice cover. It is a different kind of writing.

Principles

1. Zero untranslated jargon. "Monorepo" becomes "a single repository". "Multi-tenant" becomes "each company with its data isolated". "CI/CD" becomes "every change passes automated checks before going live". If a technical term must appear, a one-sentence explanation comes with it.
2. Honest numbers. Hours, deadlines and scope reflect the real contract — never a partial version that "presents better". A wrong number in presented material is the kind of thing that erodes trust and is very expensive to fix later.
3. Document scope = contracted scope. Future phases, product vision and commercial possibilities stay out of the MVP document (at most, a one-line note: "future evolutions depend on a new commercial cycle").
4. Real team, real roles. Only people actually allocated, each with their correct role. Double-check before sending.
5. Explicit engineering principles. A short section stating how the team decides: proven technology over trends, complexity only when the problem demands it, reversible decisions, honest deadlines. Clients understand and value it — and the document becomes an anchor when someone suggests the trend of the week.

House formats

Architecture/structure document (responsive HTML):

• Sections: overview → what the system does → how it is organized (repos, modules) → team and roles → engineering principles → timeline/workstreams
• Flowing prose, tables only where comparison demands them
• No decorative Unicode borders and no emoji overload (they break rendering and age badly)

Presentation (fullscreen HTML deck):

• Keyboard (←/→) and click navigation, progress bar, slide counter
• One topic per slide, short sentences
• Export to PDF for distribution via WhatsApp/email (the PDF is what circulates; the HTML is what presents)
• Mandatory final check: deck numbers × contract numbers, before presenting

Closing email (weekly/delivery):

• What was done (verifiable facts), what comes next, items pending on the client
• Short: if it's longer than one screen, it became a report and nobody reads it

Checklist before sending any material

• [ ] Numbers match the contract/execution plan
• [ ] Team and roles verified
• [ ] Jargon translated or eliminated
• [ ] Scope limited to what was contracted
• [ ] Rendering checked on the device the client will open it on (usually a phone)