wiki style guide

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:

1. Update the updatedDate in frontmatter
2. Preserve the original style
3. Mark sections with _TODO: if incomplete
4. 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

Remember: The goal is clear, helpful documentation that respects the reader’s intelligence while being accessible to various skill levels.