WRITING_STYLE.md
Rama main · réplica de lectura del repositorio original.
# 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