public-data-docs

Documentation Contributing Guide

How to write and maintain the documentation in this repository so it stays accurate, consistent, and useful to AI coding agents and humans alike.

This repository is public. Never add secrets, credentials, private hostnames, IP addresses, or tenant identifiers to any file.

Structure

• ../AGENTS.md — top-level agent guide and index (kept under 150 lines).
• ../CLAUDE.md — a pointer file that imports AGENTS.md. Do not add content here; edit AGENTS.md instead.
• tech/ — technical setup, tooling, and CI guides, indexed by tech/README.md.
• domain/ — data model and glossary, indexed by domain/README.md.
• snowflake-data-inventory.md — data conventions, access options, and the table index.
• snowflake-tables/ — one reference document per Snowflake table.
• qliksense-reports/, reporting-general/ — reporting and KPI documentation.

Conventions

• Write LLM-agnostic prose. Refer to “AI coding agents” or “agents”, not any specific assistant by name. The only exception is the CLAUDE.md pointer file.
• Use clear #/##/### headings; do not nest deeper than ### in sub-files.
• No emojis in tech/ and domain/ sub-files. (The legacy landing-page and inventory files use emojis in section headers; leave those as-is unless reworking the page.)
• One topic per file. Cross-reference instead of duplicating content.
• Keep AGENTS.md under 150 lines and each docs/** sub-file under 300 lines.
• Table reference files use lower_snake_case.md matching the table name. Guides in tech/ and domain/ use UPPERCASE-KEBAB-CASE.md.

Adding or changing a table reference

1. Edit or add the file under snowflake-tables/.
2. Update the index in snowflake-data-inventory.md (and ../readme.md if the table is featured).
3. Add or update the entry in ../toc.json so it appears in the Stoplight navigation.
4. Preserve any stoplight-id front matter on existing files.

Keeping docs accurate

When platform data or conventions change, update the affected reference file, the glossary (domain/GLOSSARY.md), and the data model overview (domain/DATA-MODEL.md). Automated code review checks documentation PRs against the repository and flags stale content.