What This Covers

How to write and publish documentation for your product so it appears on the Tawa docs site. This guide covers doc types, naming conventions, the publishing workflow, and what every product is expected to document.

How the Docs System Works

Documentation is stored in the Bible DB and rendered automatically on the Tawa docs site. When you publish a doc, it appears within 60 seconds.

Your Claude (with jci-mcp) → Bible DB → docs.tawa.insureco.io

You write docs using the jci-mcp Bible tools — no pull requests, no file formats to manage. Docs are markdown with a small set of structured fields.

Your Product Namespace

Every service gets its own namespace in the docs system, matching the metadata.name from your catalog-info.yaml.

If your service is named raterspot, your docs live under:

raterspot/guide/getting-started
raterspot/reference/api
raterspot/guide/testing

The full identifier is always {product}/{type}/{slug}.

Doc Types

Use guide when you're teaching someone how to do something.

Use reference when you're documenting what something is or does — inputs, outputs, config fields, env vars.

Use changelog when you're shipping a breaking change or deprecating something devs depend on.

Minimum Required Docs

Every product deployed on Tawa must have at minimum:

{product}/guide/getting-started     — How to use or integrate your product
{product}/guide/testing             — How to test integrations locally and in sandbox
{product}/reference/api             — Endpoints, request/response schemas, auth requirements

These are reviewed as part of the Tawa partner onboarding process.

Publishing Workflow

Docs go through a simple lifecycle: draft → published.

1. Create — creates a draft (not visible on the docs site)
2. Edit — update content at any time (unpublished changes don't go live)
3. Publish — makes the doc live on the docs site

Your Claude handles this via the jci-mcp Bible tools. See docs-guidelines for the full Claude workflow.

Quick example

Tell your Claude:

"Create a getting started guide for raterspot explaining how to call the rating API and what credentials are needed."

Your Claude will draft the doc, show it to you for review, then publish it.

Content Guidelines

Be specific. Don't write "configure your service" — write exactly what fields, values, and commands are needed.

Use code for everything. Every config snippet, command, and API example should be in a code block.

No internal infrastructure details. Don't mention internal hostnames, encryption algorithms, K8s secret names, or cluster DNS patterns. Describe what happens ("credentials are injected on deploy"), not how the platform does it internally.

Write for the reader's task, not your implementation. Docs answer "how do I do X?" not "here's how we built X."

Slug Conventions

Slugs are lowercase, hyphen-separated, no underscores, no spaces.

Updating Docs

Edit and republish when:

• An API endpoint or field changes
• A new config option is added
• A bug in the docs is found
• SDK versions or requirements change

NOTE: Editing a published doc updates it live immediately after republishing. Readers see the change within 60 seconds.

Getting Help

If your Claude doesn't have jci-mcp configured, contact the platform team to get MCP access set up. The full authoring spec — including Claude tool calls and content templates — is in docs-guidelines.