Documentation Model
Successful product docs usually separate orientation, task guides, conceptual models, and generated reference material. Longsurf should follow that structure for every major product surface.
Section Pattern
Section titled “Section Pattern”Each major docs area should eventually contain:
| Page type | Purpose |
|---|---|
| Overview | Explain what the surface is, who uses it, and how it fits into the platform. |
| Guides | Walk through user tasks such as creating an alert, building a watchlist, or writing an indicator. |
| Concepts | Explain the durable model: resource ownership, runtime behavior, data freshness, permissions, and limits. |
| Reference | List exact capabilities, schemas, APIs, diagnostics, or generated command surfaces. |
| Status | Distinguish implemented behavior, active rollout work, and planned capabilities. |
Correctness Rules
Section titled “Correctness Rules”- Generated facts stay generated. Tea Script capabilities are generated from TSGraph-owned metadata, and similar capability pages should follow that model.
- Product docs should name the source of truth they summarize: vision doc, package, schema, API, or runtime manifest.
- User-facing docs should use Longsurf terminology even when the repo or older vision docs still contain OpenChart names.
- A feature page should not imply launch-ready behavior unless the owner doc or code path supports that claim.
Current State
Section titled “Current State”The initial docs hierarchy is intentionally broad but shallow. It creates the right information architecture first, then leaves room to replace orientation stubs with task guides and generated references as each product area hardens.