Skip to content

Documentation Style Guide

This "meta-documentation" defines the voice, formatting, and organizational standards for anyone contributing to the project.

1. The Voice and Tone

The project should adopt an "Academic-Technical" tone. It needs to be precise enough for a developer to debug a Scrapy middleware but rigorous enough for a peer-reviewer to validate methodology.

  • Objective: Avoid first-person ("I did this"); use objective, active voice ("The scraper executes...").
  • Transparent: Clearly document limitations, such as when a site's anti-bot protection causes a 10% failure rate.

2. Structural Framework: Diátaxis

Every new page added to the docs/ folder should fit into one of these four quadrants to prevent "information sprawl":

Type Purpose Writing Style
Tutorials Learning-oriented. Step-by-step, minimal theory, focused on a successful first run.
Guides Problem-oriented. Practical steps to achieve a specific goal (e.g., "Updating Dread Spiders").
Explanations Understanding-oriented. High-level discussion on architecture, ethics, and code/framework decisions.
References Information-oriented. Technical specs, CLI arguments, and auto-generated API docs.

3. Visual and Technical Styling

Since we are using Material for MkDocs, we use its built-in components to highlight critical information:

Admonitions (Callouts)

Use standard callouts to categorize notes:

  • !!! note: For general academic context or external research links.
  • !!! abstract: For summaries of research findings or thread analysis.
  • !!! danger: For critical safety warnings regarding dark web interaction or PII handling.

Diagrams

All system flows must be documented using Mermaid.js syntax rather than static images. This ensures:

  1. Version Control: You can see changes to the architecture in Git history.
  2. Maintainability: Any contributor can update a diagram by editing the Markdown text.

4. Documentation "Rules of Engagement"

  • Docstring Mandate: Every Python class in src/onion_peeler/ must have a Google-style docstring so mkdocstrings can render it correctly.
  • Directory Mapping:
  • Scraper-specific settings belong in docs/references/.
  • Dev environment/Docker setup belongs in docs/guides/.
  • Research methodology belongs in docs/explanations/.
  • Markdown Standards: Use ATX-style headers (## Header) and ensure all code blocks specify the language (e.g., ```python) for proper syntax highlighting.

5. Metadata and Frontmatter

Every page should begin with YAML frontmatter to assist with SEO and internal searchability:

---
title: Page Title
description: Concise description of the page's contents.
status: stable # or 'draft' for ongoing research
---