ML Handbook: ML Engineering with AI
Documenting with AI/Chapter 30 of 35

Client deliverables (DOCX / PPTX / XLSX)

6 min readEdit on GitHub

Markdown is the lingua franca for engineers. DOCX, PPTX, and XLSX are the lingua franca for everyone else — clients, leadership, finance, sales, regulators. Treating them as second-class cuts you off from collaboration.

The agent drafts all three. Never deliver without manual review. The failure modes are the same as code, at a higher reputational price.

Why these formats matter

  • Clients edit DOCX in Word. Your beautiful markdown is a wall of unfamiliar syntax. The PM cannot redline it. The lawyer cannot track-change it.
  • Executives consume PPTX. Decisions get made in slides. A 30-page technical report nobody reads loses to a 10-slide deck someone does.
  • Finance and ops live in XLSX. A workbook with a sortable table is more useful to them than a static markdown table.

These are not "downgrades from real docs." They are the contract surface for non-engineering stakeholders. Treat them that way.

Generation tooling

FormatBest pathNotes
DOCXpandoc from markdown, or python-docx for programmaticPandoc is fast for prose; python-docx for tables and templating
PPTXpython-pptx, or markdown→pptx via marp/pandocpython-pptx for control; marp/pandoc for speed
XLSXopenpyxl or xlsxwriter (write); pandas.to_excel (quick)xlsxwriter has better formatting; openpyxl handles templates

Reach for a template the agent can fill, not a script that builds the file from scratch. Templates preserve client branding, keep formatting under designer control, and reduce the surface where the agent can introduce ugly output.

A working pattern

Loading diagram…

Two principles:

  1. Source of truth lives in markdown / scripts / data. The DOCX/PPTX/XLSX is rendered output. If you find yourself editing the rendered file directly, you've lost the source-of-truth contract.
  2. Regenerate from scratch each time. Don't manually edit one slide and regenerate the rest. Either everything regenerates, or nothing does.

What the agent gets wrong (high stakes)

Each of these has happened. Each costs trust.

  • Numbers in the rendered slide don't match the markdown source. The generation script took a slightly different value (older log, different rounding, wrong sheet).

  • Charts use placeholder data. The agent generated a chart from "example" data instead of real data and forgot to swap.

  • Confidential data in the wrong cell. Internal salaries, customer names, PII pasted into a deck meant for an external client. The agent does not know which strings are sensitive unless told.

  • Wrong client logo / wrong client name. Last week's template, forgot to update.

  • Mixed languages on a single-language deliverable. An English slide with a Vietnamese caption — keep each surface monolingual.

  • AI tool disclosure showing in places it shouldn't (keep this rule: no AI disclosure on public client pages unless explicitly approved).

Run a manual review pass with these specifically in mind. They are not caught by spell-check.

Pre-delivery checklist

Print this. Use it on every external deliverable.

  • Every number traces to a source (markdown, script output, dataset cell).
  • Every chart was generated from production data, not example/placeholder data.
  • Client name, logo, and project ID are correct.
  • No internal-only data, names, or links present.
  • No AI tool disclosure unless authorized.
  • Language is consistent across all surfaces (no mixing).
  • Page numbers, table of contents, and cross-references are valid.
  • Hyperlinks resolve to public URLs (not localhost, not internal SharePoint).
  • File metadata (author, last modified by) does not leak the wrong identity.
  • Filename is per the client's naming convention.

A 10-minute walkthrough. Catches what the agent missed.

DOCX-specific guidance

  • Use a styled template with defined heading styles, table styles, and a named cover page. Pandoc respects them when given via --reference-doc.
  • Track-change-friendly: don't use heavy character formatting that obscures redlines. Plain prose, simple bullets, real headings.
  • Tables: real Word tables, not markdown tables rendered as text. The agent should generate using python-docx or pandoc with a styled reference.
pandoc report.md \
 --reference-doc=templates/client-template.docx \
 -o output/2026-05-04-report.docx

PPTX-specific guidance

  • Slides have a layout. Stick to one of: title, title+content, two-column, full-bleed image. Don't let the agent invent layouts.
  • One idea per slide. Densely packed slides read worse than two simpler ones.
  • Speaker notes go in notes placeholders, not in the slide body.
  • Charts: generate as images from a Python script (matplotlib, plotly→png), insert into the slide. Never let the agent freehand a chart in the deck.
# scripts/render_deck.py
from pptx import Presentation
prs = Presentation("templates/client-template.pptx")
slide = prs.slides.add_slide(prs.slide_layouts[1]) # title+content
slide.shapes.title.text = "Quarterly results"
#... fill in body...
prs.save("output/2026-05-04-deck.pptx")

XLSX-specific guidance

  • Headers in row 1. Filterable. Frozen.
  • One sheet per logical concept. Don't pile everything on "Sheet1."
  • Numbers as numbers, not strings. Money formatted with currency symbols. Dates as dates.
  • A "README" sheet for any non-trivial workbook: column definitions, source, refresh cadence, last refresh timestamp.
  • Avoid macros unless the client explicitly needs them. They are flagged by many enterprise email systems.
import pandas as pd
with pd.ExcelWriter("output/2026-05-04-report.xlsx", engine="xlsxwriter") as w:
    df.to_excel(w, sheet_name="Results", index=False)
    meta_df.to_excel(w, sheet_name="README", index=False)
    w.sheets["Results"].autofilter(0, 0, len(df), len(df.columns) - 1)

Versioning the rendered files

The rendered DOCX/PPTX/XLSX are derived artifacts. Two patterns:

  • Don't commit them. Commit the source (markdown, scripts, data refs); regenerate when needed; archive a copy of each delivered file in a read-only deliveries/<date>-<client>/ directory or external storage.
  • Commit them with a clear naming convention (2026-05-04-clientname-v1.docx). Useful when you need traceability of exactly what was sent.

Pick one. Be consistent. The worst pattern is "sometimes committed, sometimes not" — nobody knows which version was the one delivered.

Stakes

The client sees the deliverable, not the markdown. A wrong number in a deck is a wrong number to the client. They will not check the script that produced it. Your reputation rides on the rendered output, not the upstream source.

Apply numbers-must-be-measured with extra strictness. Deliver fewer claims; make every one defendable.