feat: docs v2 (#2460)

Co-authored-by: Catalin Pit <catalinpit@gmail.com>
2026-06-22 04:12:06 +10:00 · 2026-02-27 22:05:27 +11:00
parent f8ac782f2e
commit b92c53dbb2
290 changed files with 32521 additions and 266 deletions
@@ -0,0 +1,343 @@
+# Documentation Writing Style Guide
+
+This document defines the writing conventions for Documenso documentation.
+
+Documentation lives in `apps/docs/` as MDX files and uses [Fumadocs](https://fumadocs.dev).
+
+## Core Principles
+
+1. **Task-based navigation** - Organize by what users want to do, not by feature hierarchy
+2. **Progressive examples** - Start simple, build to complex
+3. **Explicit limitations** - List what's NOT supported clearly
+4. **Real-world context** - Explain document signing concepts with familiar comparisons
+
+## Tone
+
+- Direct and action-oriented
+- Second person ("you") with imperative voice
+- Technical but accessible
+- Acknowledge complexity without condescension
+- No emojis or excessive personality
+
+## Anti-Patterns to Avoid
+
+- Assuming document signing domain knowledge
+- Hiding default values
+- Separate "TypeScript" sections (types integrated throughout)
+- Monolithic single-page references
+- Examples that don't work with current API
+
+## Documentation Audiences
+
+The docs serve three distinct audiences:
+
+1. **Users** - People using the Documenso web application to send and sign documents
+2. **Developers** - Building integrations with the API or SDKs
+3. **Self-hosters** - Running their own Documenso instance
+
+Tailor content to the audience:
+
+- User docs: Focus on UI workflows, no code required
+- Developer docs: API/SDK examples, authentication, webhooks
+- Self-hosting docs: Deployment, configuration, infrastructure
+
+## File Structure
+
+```
+apps/docs/
+├── index.mdx              # Landing page with audience navigation
+├── getting-started/       # Quick starts for each audience
+├── users/                 # Application usage guides
+│   ├── documents/         # Creating and managing documents
+│   ├── templates/         # Working with templates
+│   ├── signing/           # Signing documents
+│   └── settings/          # Account and team settings
+├── developers/            # API and SDK documentation
+│   ├── api/               # REST API reference
+│   ├── sdk/               # SDK guides
+│   ├── webhooks/          # Webhook integration
+│   └── examples/          # Code examples and recipes
+├── self-hosting/          # Self-hosting documentation
+│   ├── deployment/        # Deployment guides
+│   ├── configuration/     # Environment and settings
+│   └── maintenance/       # Upgrades and backups
+├── concepts/              # Shared concepts across audiences
+└── migration/             # Migration guides
+```
+
+Each directory has a `meta.json` controlling navigation order:
+
+```json
+{
+  "title": "Section Title",
+  "pages": ["index", "page-one", "page-two"]
+}
+```
+
+Use `---Label---` for section dividers in `meta.json`.
+
+## MDX Frontmatter
+
+Every page needs frontmatter for search and SEO:
+
+```yaml
+---
+title: Working with Pages
+description: Add, remove, reorder, copy, and merge PDF pages.
+---
+```
+
+## Page Structure
+
+### User Documentation
+
+```mdx
+---
+title: Feature Name
+description: Brief description for SEO and previews.
+---
+
+# Feature Name
+
+Brief description of what this does and when to use it.
+
+## Steps
+
+1. Navigate to **Settings > Feature**
+2. Click **Add New**
+3. Fill in the required fields
+
+---
+
+## See Also
+
+- [Related Guide](/docs/users/related)
+```
+
+### Developer Documentation
+
+```mdx
+---
+title: Feature Name
+description: Brief description for SEO and previews.
+---
+
+# Feature Name
+
+Brief description of what this does and when to use it.
+
+## Quick Start
+
+\`\`\`typescript
+// Minimal working example
+\`\`\`
+
+---
+
+## Section Name
+
+Content organized by task or concept.
+
+---
+
+## See Also
+
+- [Related Guide](/docs/developers/related)
+```
+
+### Self-Hosting Documentation
+
+```mdx
+---
+title: Configuration Topic
+description: Brief description for SEO and previews.
+---
+
+# Configuration Topic
+
+Brief description of what this configures.
+
+## Environment Variables
+
+| Variable   | Required | Default | Description  |
+| ---------- | -------- | ------- | ------------ |
+| `VAR_NAME` | Yes      | -       | What it does |
+
+---
+
+## See Also
+
+- [Related Guide](/docs/self-hosting/related)
+```
+
+## Parameter Tables
+
+Use Sharp-style nested parameter tables for developer documentation (API/SDK):
+
+```markdown
+### methodName(param, options?)
+
+Description of what the method does.
+
+| Param               | Type      | Default  | Description           |
+| ------------------- | --------- | -------- | --------------------- |
+| `param`             | `string`  | required | What it does          |
+| `[options]`         | `Options` |          |                       |
+| `[options.setting]` | `boolean` | `false`  | Nested option         |
+| `[options.timeout]` | `number`  | `5000`   | Another nested option |
+
+**Returns**: `Promise<Result>`
+
+**Throws**:
+
+- `SpecificError` - When something goes wrong
+```
+
+Key conventions:
+
+- Square brackets `[param]` indicate optional parameters
+- Nested options indented with `[options.name]` pattern
+- Always show default values
+- Group related options under their parent
+
+## Code Examples
+
+For developer documentation, use progressive complexity:
+
+```typescript
+// Basic usage
+const document = await documenso.documents.create({
+  title: "Contract",
+  file: pdfBuffer,
+});
+
+// With recipients
+const document = await documenso.documents.create({
+  title: "Contract",
+  file: pdfBuffer,
+  recipients: [{ email: "signer@example.com", name: "John Doe" }],
+});
+
+// Full example with error handling
+try {
+  const document = await documenso.documents.create({
+    title: "Contract",
+    file: pdfBuffer,
+    recipients: [{ email: "signer@example.com", name: "John Doe" }],
+  });
+} catch (error) {
+  if (error instanceof DocumentError) {
+    // Handle document creation error
+  }
+}
+```
+
+### Example Guidelines
+
+- All examples must be valid TypeScript
+- Show imports when not obvious
+- Include expected output in comments where helpful
+- Use realistic values, not `foo`/`bar`
+
+## UI Instructions
+
+For user documentation, use clear step-by-step instructions:
+
+- Bold UI elements: **Settings**, **Save**, **Documents**
+- Use `>` for navigation paths: **Settings > Team > Members**
+- Number sequential steps
+- Include screenshots sparingly for complex workflows
+- Describe what the user should see after each action
+
+## Callouts
+
+Use Fumadocs callouts sparingly for important information:
+
+```mdx
+<Callout type="info">Informational note about behavior.</Callout>
+
+<Callout type="warn">Warning about potential issues or breaking changes.</Callout>
+
+<Callout type="error">Critical warning about data loss or security.</Callout>
+```
+
+Reserve callouts for:
+
+- Beta/unstable features
+- Security considerations
+- Common mistakes
+- Breaking changes
+
+## Tables
+
+Use tables for:
+
+- Feature matrices
+- Parameter documentation
+- Comparison charts
+- Error catalogs
+
+```markdown
+| Feature          | Status | Notes                    |
+| ---------------- | ------ | ------------------------ |
+| Email signing    | Full   | All recipient types      |
+| Embedded signing | Full   | Via SDK or direct links  |
+| Templates        | Full   | Create and use templates |
+```
+
+## Linking
+
+- Link to related docs: `[Documents](/docs/api/documents)`
+- Use relative paths within docs
+- Add "See Also" sections for discoverability
+
+## Error Documentation
+
+Categorize errors by when they occur:
+
+```markdown
+## Document Errors
+
+Thrown when creating or updating documents.
+
+### InvalidDocumentError
+
+Document could not be processed.
+
+**Common causes:**
+
+- File is not a valid PDF
+- File exceeds size limits
+
+**Solution:** Verify the file is a valid PDF within size limits.
+```
+
+## Concept Explanations
+
+Use analogies for document signing concepts:
+
+```markdown
+Think of a **signing workflow** like passing a physical document around an office.
+
+Each recipient gets the document in turn, adds their signature or initials,
+and passes it to the next person. The **document status** tracks where it
+is in this journey.
+```
+
+## Self-Hosting Specific
+
+For self-hosting documentation:
+
+- Always specify required vs optional environment variables
+- Include example `.env` snippets
+- Document Docker and non-Docker approaches where applicable
+- Link to troubleshooting for common deployment issues
+- Specify minimum system requirements
+
+## Maintenance
+
+- Include types inline so docs don't get stale
+- Reference source file locations for complex behavior
+- Update examples when API changes
+- Test all code examples work
+- Keep environment variable documentation in sync with actual defaults