MyUCSpace documentation style guide

Author:

Zhenyu Yang <yangzhenyu@sust.edu.cn>

Date:

May 8, 2026

This style guide defines the conventions for writing and maintaining documentation in the MyUCSpace project. All contributors should follow these rules so that the documentation stays consistent, readable, and easy to maintain.

The guide draws on recommendations from the Google Developer Documentation Style Guide, the Microsoft Writing Style Guide, the Sphinx documentation, and the Linux kernel documentation guide.

General principles

Write for the reader

Documentation exists to help the reader accomplish a task or understand a system. Before you write, ask: Who is reading this, and what do they need to do? Structure the content around their goals, not around internal implementation details.

Be clear and concise

Prefer short, direct sentences. Every word should earn its place. If a sentence can be cut without losing meaning, cut it.

Good: The endpoint returns the existing session and sets created to false.

Bad: It should be noted that the endpoint will, in such a case, return the already existing session object and the created field will be set to false as a result.

Be consistent

Follow the conventions in this guide and match the style of existing pages. Consistency reduces cognitive load and makes the documentation easier to scan.

Be accurate

Keep examples, parameters, and response samples in sync with the actual code. Outdated documentation is worse than no documentation.

Voice and tone

• Use a professional but approachable tone. Write as you would explain something to a competent colleague.

• Use second person (you) for instructions and procedures. Avoid first person (we, I) except in release notes or changelogs.

  Good: To restart the backend, run the following command.

  Bad: We can restart the backend by running the following command.

• Prefer the imperative mood for procedural steps.

  Good: Click Submit.

  Bad: You should click Submit.

• Use the present tense to describe system behavior.

  Good: The endpoint returns a paginated list.

  Bad: The endpoint will return a paginated list.

• Avoid humor, slang, and culturally specific idioms. The audience may not share your context.

Document structure

License header

Every .rst file must begin with the SPDX license identifier:

.. SPDX-License-Identifier: GPL-3.0-or-later

Leave one blank line after the license header before the page title.

Field list

For developer-oriented documents (architecture, deployment guides), include an Author and Date field list after the title:

:Author: Your Name <email@example.com>
:Date:   Apr 24, 2026

Use the date format Mon DD, YYYY (e.g. Mar 22, 2026). Update the date when you make substantive changes.

API reference pages do not need an author or date field list.

Page title

• The page title is the only heading decorated with overline and underline using =:

  ==================
  Page Title Here
  ==================
  

• Keep titles short and noun-based. Use sentence case (capitalize only the first word and proper nouns):

  Good: Backend architecture overview

  Bad: The Backend Architecture Overview

Section headings

Use the following underline characters in this order, without overlines:

1. = (equals) — page title (with overline) and top-level sections

2. - (hyphen) — second-level sections

3. ~ (tilde) — third-level sections

4. " (double quote) — fourth-level sections (avoid if possible)

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

First-level heading
===================

Second-level heading
--------------------

Third-level heading
~~~~~~~~~~~~~~~~~~~

The underline must be at least as long as the heading text. Use the same character at the same nesting level throughout a single file.

Do not number headings manually (1.2.3 Title). The numbering comes from the toctree or autosectionlabel extension.

Table of contents

For long pages, add a local table of contents after the introduction:

.. contents::
   :local:
   :depth: 2

Use :depth: 2 unless the page has deeply nested content that requires three levels.

reStructuredText formatting

Inline markup

• Bold (**text**): UI elements the reader clicks or selects (buttons, menu items, tabs), and for emphasis where necessary.

• Italic (*text*): introduce new terms on first use, book titles, and words used as words.

• Literal (``text``): code, file paths, environment variable names, HTTP methods, API paths, field names, and anything the reader would type or see verbatim.

  Good: Set FILE_STORAGE_BACKEND to s3.

  Bad: Set FILE_STORAGE_BACKEND to s3.

Do not combine inline styles (e.g. ***bold italic*** or **``literal``**). Use one style at a time.

Lists

Bullet lists

Use the - character as the bullet. Indent continuation lines by three spaces so they align with the text of the first line:

-  First item.
-  Second item with a long description that wraps
   to the next line.
-  Third item.

Enumerated lists

Use auto-enumeration (#.) unless the numbers carry meaning (e.g. step-by-step procedures where the order matters and readers may reference step numbers):

#. First step.
#. Second step.

Definition lists

Use definition lists for term–description pairs:

term
    Definition of the term.

another term
    Another definition.

Code blocks

Use the .. code-block:: directive with an explicit language specifier. Do not use the shorter .. code:: form — the explicit directive makes the language unambiguous and is the convention recommended by Sphinx.

.. code-block:: bash

   docker compose up --build -d

Common language specifiers used in this project:

• bash — shell commands

• python — Python source code

• json — JSON request/response bodies

• text — plain text output, directory trees, or untyped content

Indent the code content by three spaces relative to the directive.

For inline code, use double backticks:

Run ``manage.py migrate`` to apply database migrations.

Leave exactly one blank line between the .. code-block:: directive and the first line of code. Additional blank lines will produce an unwanted empty line at the top of the rendered code block.

Tables

Simple tables (==== style) are acceptable for small datasets with few columns. For anything more complex, use grid tables (+---+ style) or the .. list-table:: directive.

Always align column delimiters and pad cells so the source is readable in plain text.

+--------------+-------------------------------------+
| Service      | URL                                 |
+==============+=====================================+
| Frontend     | http://localhost:3000               |
+--------------+-------------------------------------+
| Backend API  | http://localhost:8000/api/v1/       |
+--------------+-------------------------------------+

Admonitions

Use admonitions sparingly — only when the reader must not miss the information. Supported directives:

• .. note:: — helpful supplementary information.

• .. warning:: — potential data loss, security risk, or breaking change.

• .. tip:: — a shortcut or best practice.

• .. important:: — something the reader must be aware of before proceeding.

.. warning::

   This will delete all local development data in Docker volumes.

Keep admonition text concise. If the explanation is long, restructure it into a proper section with the admonition as a one- or two-sentence callout.

Cross-references and links

Internal references

Use :doc: for links to other pages in the documentation:

:doc:`/dev/backend/architecture`

Use :ref: for links to a specific section (requires a label):

.. _checkin-sessions:

Check-in Sessions
-----------------

See :ref:`checkin-sessions` for details.

Place the label on the line immediately above the heading, with one blank line between the label and the heading. Prefix labels with a module or topic identifier to avoid collisions (e.g. checkin-sessions, not sessions).

External references

Use anonymous hyperlinks for URLs that appear once, and named references for URLs cited multiple times:

For details, see the `Django documentation`__.

__ https://docs.djangoproject.com/

Named reference (reusable):

See the `Google Style Guide`_ for details.

.. _Google Style Guide: https://developers.google.com/style

Avoid bare URLs in the text. Always give the link a readable label.

Substitutions

For values that appear repeatedly (project name, version), define a substitution at the top of the file and use it throughout:

.. |project| replace:: MyUCSpace

Welcome to the |project| documentation.

API documentation

This section covers conventions specific to API reference pages.

Endpoint heading

Each endpoint gets its own section. The heading should be a short, imperative or descriptive phrase, not the HTTP method and path:

Submit an abuse report
----------------------

List abuse reports
------------------

HTTP method and path

Place the HTTP method and path in a code block immediately after the heading:

.. code-block:: bash

   POST /api/v1/abuse

Request body

Label the body section as Request body (not just Body) and use a .. code-block:: json directive:

Request body:

.. code-block:: json

   {
     "classroom_id": 121,
     "description": "The classroom is occupied by unauthorized people."
   }

Query parameters

Use a definition list for query parameters. Mark optional parameters with (optional):

Query parameters:

course_id
    Filter by course ID. (optional)
status
    Filter by session status. (optional)

Permissions

Use a Permissions section (not Permission) and list the access rules as a bullet list:

Permissions:

-  ``superadmin/secretary/assistant``: view all sessions.
-  Teachers: view only sessions for courses they teach.
-  Students: view only their own records.

Use backtick-quoted role names (``superadmin``) when referring to system roles.

Response examples

Label response sections as Example response (not just Response) to make it clear the payload is illustrative:

Example response:

.. code-block:: json

   {
     "code": 0,
     "message": "success",
     "data": { ... }
   }

For large JSON objects, use ... (ellipsis) to omit repetitive or less relevant fields rather than including the full payload.

Notes

Use a Notes section (not Note) for additional behavioral information that does not fit into the structured fields above:

Notes:

-  Creating a session repeatedly for the same ``occurrence`` does not
   generate duplicate data.
-  The endpoint returns the existing session and sets ``created`` to
   ``false``.

Writing for an international audience

• Use simple sentence structures. Avoid multiple subordinate clauses.

• Prefer common English words over rare or literary ones.

• Avoid idioms, metaphors, and culture-specific references that may not translate well.

• Use ISO 8601 for dates (2026-03-09) and 24-hour time (14:30, not 2:30 PM).

• When specifying time, always include the timezone offset or state the timezone explicitly (2026-03-09T08:00:00+08:00).

• Use metric units unless the context requires otherwise.

Grammar and punctuation

• Use the Oxford comma in lists of three or more items:

  Good: Users, classrooms, and courses

  Bad: Users, classrooms and courses

• Place one space after a period, not two.

• Do not use double punctuation at the end of a sentence (e.g. !., ?.).

• Use sentence case for headings. Do not capitalize words solely because they are “important”:

  Good: Check-in session list

  Bad: Check-In Session List

• Hyphenate compound modifiers before a noun:

  Good: cross-module dependencies

  Bad: cross module dependencies

• Do not hyphenate adverbs ending in -ly:

  Good: newly created session

  Bad: newly-created session

• Use e.g. and i.e. with commas on both sides, or prefer the English equivalents for example and that is for clarity.

Terminology and naming

• Use the same term consistently throughout the documentation. Do not alternate between synonyms (e.g. session vs. check-in session vs. attendance session).

• When introducing a new term, define it on first use and use the defined term thereafter.

• Capitalize product names as the product does (Django, MySQL, Docker, WeChat).

• Use lowercase for generic technology terms (api, database, server), even in headings, unless the word is a proper noun or starts a sentence.

• Write role names in lowercase and wrapped in double backticks: ``superadmin``, ``secretary``, ``assistant``.

File organization

• One topic per file. If a file grows too long, split it into separate pages and link them from a parent page using .. toctree::.

• Keep file names lowercase with hyphens as separators (https-deployment-guide.rst, not HTTPS_Deployment_Guide.rst).

• API reference files are organized under docs/api/. Development guides live under docs/dev/. Deployment and operations content lives under docs/ops/.

• Add new pages to the appropriate .. toctree:: in the parent index.rst so Sphinx includes them in the build.

Common mistakes to avoid

• Missing license header. Every .rst file must start with the SPDX identifier.

• Using ``.. code::`` instead of ``.. code-block::``. Always use the explicit form with a language specifier.

• Inconsistent heading characters. Check the heading hierarchy before adding a new section.

• Bare URLs. Always provide a readable label for hyperlinks.

• Outdated examples. Verify that code samples, request/response payloads, and parameter lists match the current implementation.

• Missing permissions section. Every API endpoint must document which roles can access it.

• Ambiguous pronouns. Rewrite sentences where it, this, or they could refer to more than one antecedent.