34 — Documentation Strategy

Where each kind of writing lives, who it’s for, and how it’s maintained. Without this, content sprawls into seven places and developers can’t find anything.

Audiences

Three primary audiences, each with different needs:

1. App authors — building Locara apps. Need: how-to, API reference, examples.
2. End users — using Locara apps. Need: install help, FAQ, troubleshooting.
3. Framework contributors — improving Locara itself. Need: spec, ADRs, contribution guide.

Documentation surfaces map to audiences:

Audience       Primary surface
────────────   ──────────────────────────
App authors    docs.<domain> (handbook + reference)
End users      help.<domain> (FAQ + support)
Contributors   github.com/<org>/locara (spec, ADRs, README)

Cross-traffic happens (an app author might dig into the spec; a contributor might need install help) but the primary entry points are distinct.

Surface inventory

Where every kind of writing lives:

Type	Location	Format	Audience
Manifesto	<domain>/manifesto	Markdown, prose	All
Spec	repo/spec/	Numbered MD docs	Contributors (mostly)
ADRs	repo/docs/adr/	Numbered MD	Contributors
Notes	repo/notes/	Research MD	Contributors
App author handbook	docs.<domain>	Astro/Next site	App authors
API reference	docs.<domain>/api	Auto-generated from JSDoc/rustdoc	App authors
CLI reference	docs.<domain>/cli	Auto-generated from clap definitions	App authors
Tutorial / quickstart	docs.<domain>/tutorial	Step-by-step prose	App authors
Examples	repo/examples/ + linked from docs	Runnable code	App authors
End-user help	help.<domain>	FAQ + articles	End users
Privacy / safety guides	<domain>/privacy and <domain>/security	Plain-language	All
Blog / devlog	<domain>/blog	Long-form posts	All
Changelog	repo/CHANGELOG.md + per-package	Markdown	All
Inline JSDoc / rustdoc	Source files	Code comments	App authors (via tab completion)
README	Each repo / package	Markdown	Contributors + casual visitors
Code of Conduct	repo/CODE_OF_CONDUCT.md	Markdown	Contributors
Contributing guide	repo/CONTRIBUTING.md	Markdown	Contributors
Legal docs	repo/legal/ + <domain>/legal	Markdown	All (legal review)

Writing principles

Adopted across all surfaces:

1. Plainspoken first. Every doc is in clear English first; technical depth follows. The hierarchy is: tagline → 1-paragraph summary → details.
2. Examples > prose. Show the thing working before explaining the theory.
3. Tested where possible. Code examples in docs are validated by CI (broken examples = broken docs = broken project).
4. Short paragraphs, frequent headings. Skimmable.
5. Inline links to related concepts. Don’t make the reader hunt.
6. No marketing speak. Locara docs read like a careful colleague’s notes, not a pitch deck.
7. Versioned where state matters. API reference is per-version; tutorials may have version banners; ADRs are immutable.

The brand voice from 29-branding.md applies: calm, precise, plainspoken, warm-but-not-folksy.

App author handbook (docs.<domain>)

The single most important docs surface. Structure:

docs.<domain>/
├── (root)              — Quickstart: 60-second demo loop
├── /tutorial           — Build your first Locara app
├── /concepts           — Manifest, capabilities, modalities, tooling, runtime
├── /guides             — Recipes for common patterns
│   ├── /chat-app
│   ├── /transcription
│   ├── /document-processing
│   ├── /agent-loops
│   └── /tool-creation
├── /reference          — Auto-generated from source
│   ├── /sdk            — TypeDoc output for @locara/sdk
│   ├── /components     — Each component with props + examples
│   ├── /cli            — Each command with flags
│   └── /manifest       — JSON Schema rendered as docs
├── /publish            — How to publish to the registry
├── /troubleshooting    — Common errors + fixes
└── /faq                — App author FAQ

Built with Astro + Markdoc (or similar SSG that handles MDX). Code blocks have copy buttons; live-runnable examples where feasible.

API reference

Auto-generated from source comments. Three sources:

• TypeScript: TypeDoc generates HTML from JSDoc.
• Rust: rustdoc for crates that are public API (limited; mostly framework-internal).
• CLI: custom generator from clap definitions.

Rule: every public function, type, and capability has a JSDoc / rustdoc block with at least:

• Description (what it does).
• Parameters / fields.
• Return value.
• One example.
• Capability requirement (where applicable).
• Since-version tag.

Missing JSDoc is a CI lint error for public items.

End-user help (help.<domain>)

Less code-heavy; written for someone who’s never opened a terminal:

• “How do I install a Locara app?”
• “Why did Transcribe ask for microphone permission?”
• “How do I export my data?”
• “How do I uninstall and reclaim disk space?”
• “What does the ‘fully local’ badge mean?”
• “I think I encountered a bug — what do I do?”

Articles are short, screenshot-rich, and don’t assume technical literacy.

Built with the same SSG as docs.<domain> for consistency, but with simpler design and search.

Tutorial / quickstart

The 5–10 minute walkthrough that builds a real (small) Locara app. Tested in CI.

Steps:

1. locara init transcribe my-first-app
2. cd my-first-app && locara dev
3. Open the dev panel; explain what’s there.
4. Edit src/App.tsx to add a feature.
5. Add a capability declaration.
6. locara test and locara verify.
7. Run locara build.
8. Optionally: locara publish (with placeholder publisher).

This is the primary “convince me Locara is good” surface for new developers.

Examples (repo/examples/)

Small, runnable Locara apps demonstrating specific patterns:

• chat-basic/ — simplest possible chat app.
• chat-with-tools/ — chat + tool calling.
• transcription-live/ — live STT.
• transcription-batch/ — batch file processing.
• rag-basic/ — embed + vector search.
• multi-app-ipc/ — Transcribe → DocVault pattern.
• voice-to-voice/ — full voice assistant skeleton.

Each is a complete, lockfile-tracked Locara project. CI builds and tests them on every PR. Linked from the handbook + included in locara init template options.

Blog / devlog

<domain>/blog. Two types of posts:

1. Devlog (weekly). Short. What was shipped this week. Open issues, decisions made. Builds the audience over time. Tone: notebook-style.
2. Long-form (occasional). Tailscale-style technical deep dives. “Why we sandbox tool execution with Wasmtime,” “How content-addressed model storage works,” “Building the capability analyzer.”

Published via the SSG. RSS feed for subscribers. Selectively cross-posted to Hacker News, Lobsters, dev.to.

Changelogs

Every package has a CHANGELOG.md following Keep a Changelog format. Generated mostly by changesets or similar tooling, edited for clarity.

Per-release notes on GitHub releases summarize the changelog entries, link to migration guides for breaking changes.

Inline source documentation

JSDoc / rustdoc on every public item. Conventions:

/**
 * Generate chat completion from an LLM.
 *
 * @example
 * ```ts
 * const response = await llm.chat({
 *   model: 'qwen2.5-3b-q4',
 *   messages: [{ role: 'user', content: 'Hello' }]
 * })
 * ```
 *
 * @capability llm.chat — requires the model in capabilities.models[]
 * @capability-extract args.model
 * @since 0.1.0
 */
export async function chat(args: ChatArgs): Promise<ChatResponse> { ... }

The capability annotations are read by the analyzer. The doc comments are read by tools like Cursor for tab completion. Both purposes served from one source.

Translation / localization

v1 is English-only across all surfaces (see 39-i18n.md). Future versions add translations starting with end-user help (highest leverage) → handbook → API reference (lowest leverage; technical English is often easier).

Maintenance + ownership

Surface	Owner	Cadence
Manifesto	Project lead	Stable; revise rarely
Spec	Project lead + maintainers	Updated with each major design decision
ADRs	Whoever made the decision	Append-only
Notes	Project lead	Append-only
Handbook	Project lead initially → docs maintainer in Phase 4+	Updated with each minor release
API reference	Auto	Per release
End-user help	Project lead initially → community-contributed in Phase 4+	As issues arise
Blog / devlog	Project lead	Weekly
Changelogs	Whoever ships the change	Per release
Inline docs	Whoever writes the code	Always

PR template includes “did you update the docs?” with a checklist.

Search

Built-in search across docs.<domain> (Astro Pagefind or Algolia DocSearch when scale justifies). End-user help has its own search. Spec is in repo, GitHub search suffices.

What we deliberately don’t do

• No video tutorials in v1. Expensive to maintain; English-only. Defer.
• No paid courses. Community can build them; we don’t.
• No “live chat” support. GitHub Issues + Discord (eventually) are the channels.
• No SLA on docs corrections. PRs welcome; respond within reason.

Open questions

• (open) Astro vs. Docusaurus vs. Next.js for docs.<domain>. Astro is favored: fast, OSS-friendly, simpler. Decision before phase 3.
• (open) AI-powered “ask the docs” widget? Feels obvious for an AI-app project, but adds infra. Phase 4+.
• (open) Versioned docs (v1.0 vs v1.1)? Probably yes for the handbook; not for the spec.

Cross-references

• Branding voice: 29-branding.md
• Manifesto: ../website/content/manifesto.md
• Phasing of when each surface goes live: 18-phasing.md
• Repo layout: 17-repo-layout.md
• Governance (who maintains what): 23-governance.md