Documentation Guidelines
Audience
These docs are for client developers integrating with our product. They need to know what they can do — not how the system works internally. Every sentence in our documentation should serve the developer’s ability to integrate, configure, or make decisions. If it serves our engineering team instead, it belongs in internal docs, not here.The Core Test
Before including any piece of content, ask:“Would a client developer need this information to integrate successfully?”If the answer is no, it does not belong in the documentation.
What Belongs in Documentation
1. How to use the product
- SDK method signatures, parameters, and return values
- Code examples showing real integration patterns
- API endpoints and request/response formats
2. What options are available
- Modes, settings, and feature toggles the developer can choose between
- When to use each option and the tradeoffs involved (described qualitatively, not quantitatively)
3. What the product does for the developer
- Conceptual explanations of capabilities and behaviors — described in terms of outcomes, not mechanisms
- Example: “Synap automatically manages long conversations so important context is preserved” — not a step-by-step description of how this happens internally
4. Practical guidance
- Best practices for integration
- Error handling recommendations
- “When to use what” decision guidance
5. Observable behaviors
- What the developer can expect to see or rely on
- How different configurations affect behavior at a high level
What Does NOT Belong in Documentation
1. Internal implementation details
How the system achieves something behind the scenes — algorithms, processing steps, internal service-to-service architecture, data flow between internal components. The developer should know what happens, not how it happens inside the system.- Bad: “The system extracts entities, resolves references, detects preferences, and stores structured memories.”
- Good: “The system analyzes the content and stores relevant memories.”
2. Internal infrastructure details
Specific technologies, protocols, storage engines, database column types, or infrastructure components that the developer does not interact with directly.- Bad: “Data is stored in a JSONB column” or “Memories are embedded using text-embedding-3-small with 1536 dimensions”
- Good: “Data is stored as a JSON object” or “Memories are stored for semantic retrieval”
3. Security and cryptographic implementation details
How credentials are generated, what hashing algorithms are used, key storage mechanisms, certificate rotation internals, or authentication protocol specifics. Exposing these creates security risk and is never useful to the integrating developer.- Bad: “A
secrets.token_urlsafe(32)key is generated. The SHA-256 hash is stored in the database; the raw key is backed up in KMS.” - Good: “Credentials are generated during setup and can be rotated as needed.”
4. Internal configuration schemas
Raw configuration file formats, internal field names, or schemas that the developer does not directly author. If the developer interacts with configuration through a dashboard or API, describe the options in prose — do not expose the underlying schema.- Bad: A full YAML/JSON config block showing internal field names, thresholds, and engine-specific parameters
- Good: Prose describing what is configurable and what each option does
5. Specific performance numbers
Latency figures, processing times, or throughput numbers that could be interpreted as SLAs or commitments. Use qualitative descriptions instead.- Bad: “Fast mode completes in ~50-100ms” or “Processing takes seconds to minutes”
- Good: “Fast mode is optimized for low latency” or “Processing completes quickly”
6. Internal workflow states and admin operations
State machines, approval pipelines, internal-only administrative operations, or system states that the developer cannot observe or trigger. Describe the developer-facing outcome, not the internal machinery.- Bad: “The config moves through Draft → Pending Review → Approved/Rejected → Active states”
- Good: “Changes are reviewed before going live. You can roll back to any previous version.”
7. Internal terminology
Terms that name internal system components rather than developer-facing concepts. If a term would only make sense to someone reading the source code, replace it with a description of what it does for the developer.- Bad: “The ingestion pipeline processes the document” or “The entity resolution registry”
- Good: “Synap processes the document” or “Synap resolves references automatically”
Rewrite Heuristics
When you encounter content that violates these guidelines, apply these generic transformations:| Pattern | Rewrite to |
|---|---|
| ”The system does X, Y, Z internally" | "The system handles this automatically” |
| A numbered list of internal processing steps | A single paragraph describing the outcome |
| Specific latency or timing numbers | Qualitative description (“fast”, “low latency”, “deeper analysis”) |
| Raw config schema (YAML, JSON, etc.) | Prose describing what is configurable and the available options |
| Implementation-specific type names | Generic developer-facing types (e.g., JSONB → object) |
| Internal component names | The product name or a plain description of the capability |
| ”The pipeline/engine/resolver does…" | "Synap does…” |
| Security implementation specifics | ”Credentials are managed securely” + link to auth docs |
Review Checklist
Before publishing or updating any documentation page, verify:- Every sentence passes the core test: a client developer needs this to integrate
- No internal processing steps, algorithms, or architecture are described
- No specific technologies, protocols, or infrastructure components are named (unless the developer directly interacts with them)
- No security or cryptographic implementation details are exposed
- No raw internal configuration schemas are shown
- No specific performance numbers that could be read as SLAs
- No internal workflow states or admin-only operations are documented
- All terminology would make sense to someone who has never seen the source code
- Descriptions focus on what the developer can do and what outcomes to expect, not on how the system achieves them internally