mirror of
https://github.com/spacedriveapp/spacedrive.git
synced 2026-10-30 04:49:32 -04:00
Jamie Pine
2d380fd264
Replaces the Mintlify setup (mint.json, docs.json, snippets) with a standalone Fumadocs app in docs/: Next.js app router, meta.json nav per section, its own bun install. Run with `just dev-docs`. Content pass alongside the migration: core architecture, data model, CLI, and networking pages rewritten around the daemon/source-store/ library split, new product-direction.mdx defining the product boundary, new drive-catalog plan, and the physical-drives plan updated to reference it. Whitepaper page retired.
139 lines
4.7 KiB
Plaintext
139 lines
4.7 KiB
Plaintext
---
|
|
title: Writing Guide
|
|
sidebarTitle: Writing Guide
|
|
---
|
|
|
|
## Writing Style
|
|
|
|
This applies to all documentation, code comments, and design documents.
|
|
|
|
Use clear, simple language. Write short, impactful sentences. Use active voice. Focus on practical, actionable information.
|
|
|
|
Address the reader directly with "you" and "your". Support claims with data and examples when possible.
|
|
|
|
Avoid these constructions:
|
|
|
|
- Em dashes (use commas or periods)
|
|
- "Not only this, but also this"
|
|
- Metaphors and cliches
|
|
- Generalizations
|
|
- Setup language like "in conclusion"
|
|
- Unnecessary adjectives and adverbs
|
|
- Emojis, hashtags, markdown formatting in prose
|
|
|
|
Avoid these words:
|
|
comprehensive, delve, utilize, harness, realm, tapestry, unlock, revolutionary, groundbreaking, remarkable, pivotal
|
|
This includes similar wording. Prefer clean, factual technical explanations.
|
|
|
|
## Rules
|
|
|
|
- Do NOT over-use bullet points
|
|
- Less code examples the better, prefer english with short examples
|
|
- You are documenting software and teaching it. Balance explanation with examples.
|
|
- Always open with a powerful introduction
|
|
- Prefer short document titles that match the sidebar
|
|
- Do not include ASCII diagrams or Mermaid diagrams.
|
|
- Opening paragraph should target 3-4 lines.
|
|
- Published documentation states the product contract. Put future design work in
|
|
`docs/plans` and durable backlog work in GitHub issues. The `.tasks` tree is
|
|
frozen.
|
|
- This is MDX meaning you can not write the less-than character without escaping it.
|
|
|
|
## Usage of custom MDX components
|
|
|
|
### Use callouts when needed, do not over-use but they are nice to see!
|
|
|
|
- <Callout>This adds a note in the content</Callout>
|
|
- <Callout type="warn">This raises a warning to watch out for</Callout>
|
|
- <Callout>This draws attention to important information</Callout>
|
|
- <Callout type="idea">This suggests a helpful tip</Callout>
|
|
- <Callout type="error">This is a danger callout</Callout>
|
|
|
|
## Code Snippets
|
|
|
|
Use code snippets sparingly to illustrate key concepts or demonstrate specific tasks:
|
|
|
|
- **When to Use**: Include snippets only when they clarify a concept better than prose or show a critical implementation detail.
|
|
- **Length**: Keep snippets short (under 10 lines when possible). Use comments to explain complex logic.
|
|
- **Formatting**: Use markdown code blocks with the appropriate language tag (e.g., ```python). Ensure snippets are complete and executable.
|
|
- **Context**: Introduce each snippet with a sentence explaining its purpose (e.g., "This code configures the API client").
|
|
- **Testing**: Verify all snippets work as intended in the specified environment. Include version numbers if relevant (e.g., "Tested with Python 3.9").
|
|
|
|
Example:
|
|
|
|
```rust
|
|
let library = core.libraries
|
|
.create_library("Jeff's Library", None)
|
|
.await?;
|
|
```
|
|
|
|
### Code Groups when showing multiple languages
|
|
|
|
- `<Tabs items={['rust', 'swift', 'typescript']}>` with a `<Tab value="...">` per language
|
|
|
|
### Always use expandable for long code blocks
|
|
|
|
```rust
|
|
pub struct Sidecar {
|
|
pub id: i32,
|
|
pub content_uuid: Uuid, // FK to ContentIdentity
|
|
|
|
// Classification
|
|
pub kind: String, // "thumbnail" | "preview" | "metadata"
|
|
pub variant: String, // Size/quality variant
|
|
pub format: String, // File format
|
|
|
|
// Storage
|
|
pub rel_path: String, // Relative path to sidecar
|
|
pub source_entry_id: Option<i32>, // Reference to existing file
|
|
|
|
// Metadata
|
|
pub size: i64,
|
|
pub checksum: Option<String>,
|
|
pub status: String, // "pending" | "processing" | "ready" | "error"
|
|
pub version: i32,
|
|
|
|
pub created_at: DateTime<Utc>,
|
|
pub updated_at: DateTime<Utc>,
|
|
}
|
|
```
|
|
|
|
### Set parameters for API or SDK references
|
|
|
|
- `param` `string` (required): An example of a parameter field
|
|
|
|
### Show steps for sequential flows, only is needed
|
|
|
|
<Steps>
|
|
<Step>
|
|
#### First Step
|
|
|
|
These are instructions or content that only pertain to the first step.
|
|
</Step>
|
|
<Step>
|
|
#### Second Step
|
|
|
|
These are instructions or content that only pertain to the second step.
|
|
</Step>
|
|
<Step>
|
|
#### Third Step
|
|
|
|
These are instructions or content that only pertain to the third step.
|
|
</Step>
|
|
</Steps>
|
|
|
|
### Tooltips
|
|
|
|
Use tooltips to provide additional context or definitions when a user hovers over a string of text. Tooltips can include optional call-to-action links.
|
|
Example: API documentation helps developers understand how to integrate with your service.
|
|
|
|
API
|
|
|
|
Your final documentation should:
|
|
|
|
- Explain the concepts clearly
|
|
- Include relevant code examples where they add value
|
|
- Use bullet points judiciously where they help organize information
|
|
- Maintain a good flow between teaching and documenting
|
|
- Use MDX helper components when they improve the explanation
|