.. SPDX-License-Identifier: GPL-3.0-or-later =================================== MyUCSpace documentation style guide =================================== :Author: Zhenyu Yang :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`_. .. _Google Developer Documentation Style Guide: https://developers.google.com/style .. _Microsoft Writing Style Guide: https://learn.microsoft.com/en-us/style-guide/ .. _Sphinx documentation: https://www.sphinx-doc.org/ .. _Linux kernel documentation guide: https://docs.kernel.org/doc-guide/ .. contents:: :local: :depth: 2 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 :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.