dashboard-docs

Skill: Dashboard and Workflow Documentation

Use this skill whenever you create or update a dashboard or workflow. Documentation is a first-class deliverable — never skip it.

Files to Produce

For every dashboard:

docs/dashboards/<name>/readme.md       ← main documentation (you write this)
docs/dashboards/<name>/img/.gitkeep   ← placeholder until screenshots are taken
docs/dashboards/README.md             ← index (update the table)

For every workflow:

docs/workflows/<name>/readme.md
docs/workflows/<name>/img/.gitkeep
docs/workflows/README.md

---

readme.md Structure

Use a narrative-first, use-case-oriented style. The canonical reference is docs/dashboards/snowpipes-monitoring/readme.md and docs/dashboards/tasks-pipelines/readme.md — read one of them before writing.

Rules:

• All fenced code blocks must specify a language — use text for plain text, paths, or commit messages when no more specific language applies. Never leave a bare ```.
• Open with one paragraph explaining what it monitors, who it is for, and why it matters.
• Place the overview screenshot immediately after the opening paragraph, before any sections.
• Organise the body by dashboard section, not by tile. Each section gets its own ## heading.
• Embed the section screenshot at the top of each section, before the prose.
• Write narrative prose for each section: open with the question(s) the section answers, then describe each tile in terms of what it reveals and what action it drives. Avoid bare bullet lists of tile names — explain the "so what".
• Use bullet points only for compact per-tile detail (e.g. what a colour means, a data latency caveat).
• Inline a close-up screenshot for any tile whose visual requires explanation (e.g. honeycomb).
• Tables are acceptable for Dashboard Variables and Known Limitations — but not as a substitute for section prose.
• End with Required Plugins, Dashboard Variables (table), and Known Limitations.
• Do not include a "Use Cases Covered" table or a "Filtering to a Specific Use Case" section as separate headings — weave filtering guidance naturally into the relevant section prose.