How to Use This Repo¶

This documentation is maintained by the dev team and AI assistants (Claude). Everything here should be scannable in under 60 seconds.

Quick Start — Save docs via Claude Code¶

Prompt to paste into Claude Code (use this every time you want to save context)

Given all the changes we did, please save this in internal documentation
so users can see it. Please go to internal_documentation/docs/how_to_use.md
and investigate how you can write this new documentation into this repo.

If there is already documentation for this feature or topic, update it
with the new information rather than creating duplicates. If we developed
it further or tried new approaches, add those to the existing
feature_development.md.

If the feature is still in development, make sure the feature_development.md
has a Progress table at the top tracking every task with its status
(✅ Done, 🚧 TODO, ⚠️ Risk). Update it with what we just completed or
what's still left to do.

If during development you figured out how to use an external tool or
service (e.g. Auth0, SendGrid, AWS, Cloudflare, etc.), write a tutorial
for it in tech/tutorials/ so other developers can follow the same steps.

Consider this as well:
<paste any additional context here — ChatGPT research, notes, links, etc.>

Repo Structure¶

docs/
├── tech/
│   ├── news/               # Team announcements, one entry per event
│   ├── features/           # Feature specs and dev logs
│   │   ├── authentication/ # SSO, SAML setup guides
│   │   └── per_app/        # Features grouped by app
│   │       └── <app_name>/
│   │           └── <feature_name>/
│   │               ├── feature.md              # What the feature does
│   │               └── feature_development.md  # What was tried
│   ├── tutorials/          # How-to guides for external tools and services
│   │   └── <tool_or_topic>.md
│   └── repos/              # Technical docs grouped by repo/service
│       ├── 1_frontend/
│       ├── 4_connectors/
│       └── ...
└── how_to_use.md           # This file

Writing Rules¶

These apply to humans and AI equally.

General¶

One idea per page. If a page covers two topics, split it.
Lead with the answer. First sentence = what this page is about. No preamble.
Use headers aggressively. A dev scanning the page should find what they need in 5 seconds.
No prose. Bullet points and tables over paragraphs. Code blocks over descriptions.

Features (`tech/features/`)¶

Features are organized into subfolders:

Subfolder	What goes here
`authentication/`	SSO, SAML, identity provider guides
`per_app/<app_name>/<feature_name>/`	Features specific to one connector/app

Each per-app feature gets its own folder with two files:

File	Purpose	Written by
`feature.md`	What the feature does, why it exists, how it works at a high level	Anyone
`feature_development.md`	Dev log: progress tracker, what was tried, what failed, decisions made	Developers

For features still in development, feature_development.md must include a Progress table at the top tracking every task with its status. Update this table as work progresses — it's how the team sees what's done, what's left, and what's blocked.

Example path: tech/features/per_app/hubspot/associations_incremental_sync/

feature.md template:

# Feature Name

## What it does
One sentence.

## Why it exists
The problem it solves.

## How it works
High-level flow. Diagrams encouraged. No code unless essential.

feature_development.md template:

# Feature Name — Development Log

## Progress

| Task | Status | Notes |
|------|--------|-------|
| Task that is done | :white_check_mark: Done | Brief note |
| Task in progress | :construction: TODO | What's left |
| Task with risk | :warning: Risk | Why it's risky |

## What was tried
- Approach A — didn't work because X
- Approach B — worked, shipped

## Decisions
- Why we chose B over A

## Related commits
- `abc1234` — initial implementation

Status icons: :white_check_mark: Done, :construction: TODO, :warning: Risk

News (`tech/news/`)¶

One page per news item. The news index auto-lists all entries.

When to add news:

A feature is done or reaches a milestone
A feature is in progress and the team should know
Any change that affects the team

File naming: YYYY-MM-DD_short_title.md

Example: tech/news/2026-04-03_documentation_site_launched.md

Two steps to add news:

Create the file in tech/news/
Add it to the nav in mkdocs.yml under News (newest first)

Template:

# Short Title

**Date:** YYYY-MM-DD
**Status:** Done | In Progress

What happened, one paragraph max. Link to the relevant feature page if applicable.

Tutorials (`tech/tutorials/`)¶

Step-by-step guides for using external tools and services that come up during development. If you figured out how to do something (change Auth0 email templates, configure Cloudflare DNS, set up SendGrid dynamic templates, etc.), write it here so the next developer doesn't have to figure it out again.

One file per topic. Name it after the tool or action: auth0_email_templates.md, cloudflare_dns_setup.md.

Template:

# How to [Do the Thing]

## Prerequisites
- What you need before starting

## Steps
1. Step one
2. Step two

## Gotchas
- Things that tripped you up

Repos (`tech/repos/<name>/`)¶

Technical docs specific to a repo or service. Cover:

Environment variables and config
Architecture decisions specific to that repo
Gotchas and workarounds

For AI / Claude¶

When generating documentation for this repo:

Follow the folder structure above. Don't create files outside of it.
Use the templates. Don't invent new formats.
Be terse. Max 300 words per page. If it's longer, split it.
No filler. No "In this document we will..." or "This section covers...". Just write the content.
Code > words. If you can show it in a code block, don't describe it.
Link, don't repeat. If something is documented elsewhere, link to it.
Add news when a feature is done or in progress. Create a page in tech/news/ and add it to the nav in mkdocs.yml.
Write tutorials for external tools. If you helped the developer figure out how to use Auth0, SendGrid, AWS, etc., save a how-to in tech/tutorials/.
Update, don't duplicate. If docs already exist for a feature or topic, update the existing files instead of creating new ones.
{{ }} is safe in markdown. Macro processing is off by default. Content with Handlebars, Jinja2, or template syntax won't break the build.

Local Preview¶

One line, no setup needed:

docker compose up

Open http://localhost:8069 — hot reloads on every file save. First run builds the image automatically.

Deploying¶

Push to prod branch → Cloudflare Pages builds and deploys automatically.