wiki style guide

published: August 3, 2025

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

Page TypeHeading StyleToneExample
Meta/DocsTitle CaseFormal”## Getting Started”
ProgramminglowercaseDirect”## installation”
Blog PostsVariesPersonalReflective, thoughtful

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

══════════════════════════════════════════════════════════════════
on this page