SmallBlock Style Guide¶

This guide defines the writing conventions, tone, and formatting used throughout the SmallBlock CMS documentation. It ensures a consistent, professional, and readable experience for all users.

Purpose and Audience¶

SmallBlock CMS documentation is written for:

Developers and system administrators who install, configure, and extend the system.
Content editors and site managers who create and maintain content through the web interface.

The goal is to help each audience complete tasks efficiently, using language that is clear, direct, and approachable.

Tone and Voice¶

SmallBlock documentation is:

Direct — Use short, clear sentences. Avoid filler phrases like “you’ll find that…”.
Approachable — Friendly but professional. Avoid slang or humor.
Objective — Present facts without hype or opinion.
Active — Prefer active voice (“Edit the settings file”) over passive (“The settings file should be edited”).
Second-person — Speak directly to the reader (“You can…”).

Example¶

Prefer:: Run the following command to start the server.
Avoid:: You’ll find that the following command starts the server.

Grammar and Style¶

General conventions:

Use the Oxford comma. Example: “pages, posts, and media files.”
Write in American English.
Use present tense whenever possible.
Use sentence case for headings.
Avoid contractions in procedural writing (write “do not” instead of “don’t”).
Keep most sentences under 25 words.
Define acronyms on first use (e.g., “Content Management System (CMS)”).

Formatting and Structure¶

Headings¶

Follow a consistent heading hierarchy:

# Main section title
## Subsection
### Sub-subsection

Each page begins with a short summary describing its purpose.

Example introduction paragraph:

This guide explains how to install and configure SmallBlock CMS on a Linux server using Nginx and PostgreSQL.

Code and Commands¶

Use the appropriate Sphinx directives:

Command-line examples:

$ pip install smallblock
$ smallblock init myproject

Python examples:

from smallblock.plugins import register_plugin
register_plugin("gallery")

Inline references:

Use backticks for filenames and inline code:

File path: config/settings.py
Command: smallblock runserver

Admonitions¶

Use Sphinx admonitions for important notes or warnings:

Type	Purpose
`.. note::`	Supplementary information or context.
`.. tip::`	Optional hints or optimizations.
`.. warning::`	Critical caution that prevents data loss or errors.
`.. important::`	Key step required for successful completion.

Terminology¶

Use consistent terms throughout the documentation.

Term	Usage
SmallBlock CMS	Full name on first use. Thereafter, “SmallBlock.”
plugin	Lowercase, unless part of a proper name.
toolbar, wizard, template tag, webhook	Lowercase.
Administrator, Editor, Author	Capitalize when referring to specific role names.
CMS, API, CLI	Uppercase abbreviations.

Examples and Code Style¶

Use realistic examples (e.g., blog, gallery, staff_directory).
Keep code minimal but complete—examples should run if copied.
Follow PEP 8 for Python code.
Prefer clarity over brevity.

Example:

def double(value):
    """Return the given value multiplied by two."""
    return value * 2

Cross-Referencing¶

Use Sphinx cross-reference syntax to connect related topics:

See :ref:`plugin-architecture` for details.

Ensure every topic is accessible from at least one top-level index page.

Visual Aids¶

Diagrams — Use simple architecture diagrams for data flow or deployment.
Screenshots — Use neutral placeholder content (e.g., “Acme Corp Site”).
Terminal output — Use a fixed-width font and the $ prompt for shell examples.
Tables — Keep text concise; use sentence fragments where appropriate.

File and Directory Conventions¶

A typical documentation layout:

docs/
├── index.rst
├── introduction/
│   ├── overview.rst
│   ├── installation.rst
├── user-guide/
│   ├── creating-content.rst
│   ├── media.rst
├── developer-guide/
│   ├── plugins.rst
│   ├── api.rst
├── reference/
│   ├── cli.rst
│   ├── settings.rst
│   ├── style-guide.rst
└── glossary.rst

Editorial Principles¶

Every topic answers a question. (“What is it?”, “How do I use it?”, “Where is it configured?”)
Every section begins with context. Explain why the reader needs this information.
Every procedure ends with verification. Show how to confirm success.
Maintain consistency across sections.
Use examples to teach, not to impress.

Example Page Template¶

Below is the standard format for new documentation pages.

===============
Page Title
===============

Short introductory paragraph explaining what the user will learn.

.. contents:: Table of Contents
   :local:

Section Title
--------------

Step-by-step or conceptual material here.

Example code:

.. code-block:: bash

   $ smallblock runserver

.. tip::
   You can stop the server with ``Ctrl+C``.

Acknowledgment¶

This guide is adapted from internal SmallBlock CMS documentation standards and follows conventions inspired by Django, FastAPI, and Python community guides.