wiki style guide
on this page
A guide for maintaining consistent style and tone across wiki documentation.
Writing Style
Tone
The wiki uses an understated, direct, and informative tone:
- Be factual and straightforward
- Avoid marketing language or hyperbole
- Don’t try to be clever or edgy
- Let the content speak for itself
Good: “python 3.13 introduced significant performance improvements for dataclasses”
Avoid: “python 3.13 was a game-changer!” or “because guessing is for chumps”
Voice
- Use direct, clear language
- Prefer active voice when appropriate
- Keep sentences concise
- Technical accuracy over simplification
Formatting Conventions
Headings
Meta pages (in /meta/
): Use Title Case
## Quick Start
### Creating Your First Page
Technical pages (programming, tools): Use lowercase
## overview
### installation steps
This reflects a more personal, informal approach to technical documentation while maintaining formality for site documentation.
Code Blocks
Always specify the language for syntax highlighting:
```python
def example():
return "Hello"
```
Include filenames when showing specific file contents:
<CodeBlock
code={`# config.py
DEBUG = True`}
lang="python"
filename="config.py"
/>
### Lists
Use consistent markers:
- Bullets: Use `-` (not `*` or `+`)
- Numbered: Use `1.` for all items (auto-numbering)
## Content Structure
### Page Organization
1. **Frontmatter**: Complete all required fields
2. **Introduction**: Brief overview without heading
3. **Main content**: Logical sections with clear headings
4. **References**: Links to related resources
### Frontmatter Requirements
```yaml
---
title: 'lowercase for technical pages' # or 'Title Case for Meta'
description: 'clear, concise description'
category: 'Programming' | 'Meta' | 'Tools'
subcategory: 'Languages' | 'Frameworks' # if applicable
tags: ['relevant', 'searchable', 'terms']
publishDate: 2025-08-03T12:00:00Z
updatedDate: 2025-08-03T12:00:00Z
relatedPages: ['path/to/related', 'another/related/page']
draft: false
toc: true # for longer pages
---
Language Guidelines
Technical Terms
- Use standard terminology consistently
- Define acronyms on first use
- Link to documentation when introducing concepts
Commands and Code
Inline code: Use backticks for commands
, filenames
, and variables
Command examples: Show the full command
uv run --python 3.14 --with matplotlib python script.py
Emphasis
- Bold for important concepts or warnings
- Italics sparingly for emphasis
- Avoid excessive formatting
Common Patterns
Describing Features
Instead of promotional language, use factual descriptions:
Good: “uv installs packages 10-100x faster than pip”
Avoid: “uv is blazingly fast!”
Comparisons
Present objective information:
Good: “sqlalchemy operates at a different scale (50-140x slower) due to database operations”
Avoid: “sqlalchemy is slow”
Recommendations
Provide context for decisions:
Good: “for serialization-heavy workloads, pydantic maintains an advantage”
Avoid: “just use pydantic”
Examples
Technical Overview
## overview
python 3.13 introduced significant performance improvements for dataclasses.
this benchmark tracks performance evolution from python 3.10 through 3.14.
Results Section
## results
### key findings
- pydantic serializes ~2.5x faster due to rust-based implementation
- sqlalchemy operates at a different scale due to database operations
- dataclasses and pydantic have similar performance for basic operations
Page Types
Benchmark Pages
- Present data objectively
- Include methodology
- Show actual numbers
- Explain what the results mean
Library Documentation
- Start with when to use it
- Show practical examples
- Include common patterns
- Note limitations
Setup Guides
- Begin with prerequisites
- Use numbered steps for procedures
- Include verification steps
- Add troubleshooting section
Maintenance
Updating Content
When updating pages:
- Update the
updatedDate
in frontmatter - Preserve the original style
- Mark sections with
_TODO:
if incomplete - Keep examples current
Consistency Checks
Before publishing:
- Verify heading style matches page type
- Check code blocks have language specified
- Ensure frontmatter is complete
- Confirm related pages exist
Quick Reference
Page Type | Heading Style | Tone | Example |
---|---|---|---|
Meta/Docs | Title Case | Formal | ”## Getting Started” |
Programming | lowercase | Direct | ”## installation” |
Blog Posts | Varies | Personal | Reflective, thoughtful |
Remember: The goal is clear, helpful documentation that respects the reader’s intelligence while being accessible to various skill levels.
══════════════════════════════════════════════════════════════════