13.2. Conventions¶
The patterns described here have emerged from practical experience writing and maintaining this documentation. They are guidelines, not hard rules — existing pages that deviate are not wrong, and there are legitimate reasons to break a pattern in a specific context. The goal is coherence: a reader who jumps between sections should not feel like they are reading different projects, and a new author should be able to produce something that fits without spending effort on low-stakes decisions.
When in doubt: follow the existing file closest to what you are writing.
13.2.1. Folder and File Names¶
13.2.1.1. One index.md per Folder¶
Every content folder has a single entry-point file called index.md (or index.rst for older
sections written in reStructuredText). Sub-pages live in named sub-folders, each with their own
index.md.
14-Engineering-Notebooks/
PJBIO-1060-Crosssections-over-sticks/
index.md ← entry point
_figures/
Balancer/
index.md
01-Introduction-and-Goals/
index.md
Why: Sphinx/MyST assembles the navigation tree from toctree entries that point to folders.
Using index.md everywhere means every path ends the same way, toctree entries are uniform, and
readers who land on a bare folder URL always get the right page.
Advantage: The nav hierarchy mirrors the folder hierarchy exactly. Any tool that lists files alphabetically (file explorer, CI output) immediately shows which file is the section root.
13.2.1.2. Numbered Prefixes Define Reading Order¶
Top-level documentation chapters use two-digit numeric prefixes, zero-padded:
00-Project-Manual, 01-Introduction-and-Goals, …, 12-Glossary, 99-Appendix.
Folders that contain sequential content (process steps, lifecycle phases) carry a numeric prefix so that the filesystem order matches the intended reading order:
Appendix/Process_Assessment_Guide/Software_Engineering/
01_SW_Requirements_Analysis/
02_SW_Architectural_Design/
03_SW_Detailed_Design/
Why: {toctree} controls the rendered order, but file explorers, git diff output, and
directory listings all sort alphabetically. Numeric prefixes keep both views consistent.
Alternative: Rely solely on toctree order and use plain PascalCase folder names. Acceptable for non-sequential content such as service descriptions or appendix topics where no reading order applies.
13.2.1.3. Hyphens Between Words in Folder Names¶
Folder names use Title-Case words joined by hyphens:
Engineering-Notebooks, Workflow-and-Collaboration, Meeting-Minutes.
Why: Hyphens survive more contexts than spaces (URLs, shell scripts, git paths on all platforms). Title-case keeps folder names readable in filesystem listings without underscores or all-caps.
Exception: Detailed-design component folders use PascalCase without hyphens (WebGui,
DataProcessor, ViPyGrammy). These match the software component names exactly, so the folder
name doubles as an unambiguous identifier.
13.2.1.4. Engineering Notebook Folders Start with the Jira Ticket¶
14-Engineering-Notebooks/
PJBIO-1060-Crosssections-over-sticks/
PJBIO-1210-integrating-into-ecosystem-of-medicbite/
Why: Each engineering notebook is created in response to a specific ticket. Starting with the ticket ID makes the folder self-describing and makes it trivially easy to find the documentation for a given ticket both from the filesystem and from a Jira link.
13.2.1.5. Meeting-Minutes Folders Follow a Date Hierarchy¶
15-Meeting-Minutes/
2026-06-Jun/ ← year-month-abbreviation
2026CW23/ ← ISO calendar week
index.md
Why: Chronological nesting keeps the archive navigable over years. The month folder groups weeks for a quick "what happened in April" lookup; the CW folder identifies the exact week for cross-referencing meeting labels.
13.2.2. Asset Sub-Folders¶
All non-text assets live in dedicated sub-folders next to index.md, named with a leading
underscore:
Folder |
Contents |
|---|---|
|
Images ( |
|
Downloadable files: PDFs, presentations, archives |
|
Code or text files included verbatim via |
|
CSV or other structured data used by table directives |
Why the leading underscore: Sphinx/MyST ignores folders that start with _ when scanning for
documentation source files. This prevents images and PDFs from being mistakenly treated as pages,
keeps build warnings clean, and signals to any reader of the filesystem that these are supporting
assets, not content pages.
Co-location principle: Place assets in _figures/ alongside the .md file that uses them,
not in a central repository-level folder. Co-location means a section and its figures move
together when the folder structure changes, and deleting a section automatically removes its
figures.
Alternative for _attachments/: If a page links to a file that is also referenced from other
pages, place it at a higher folder level rather than duplicating it.
13.2.3. Figure File Names¶
Figure files use lowercase words joined by underscores, with no hyphens:
project_timeline.png
bd_biomech_decomposition_level_1.drawio
grammy_big_picture.drawio
sd_get_time_series.uml
Why underscores, not hyphens: Section labels reference figure names as part of their
identifier (fig_project_timeline). Underscores are valid Python identifiers and compose
naturally with the label prefix. Hyphens are not valid in label names, which would force a
mismatch between the file name and its label.
Why lowercase: Case-sensitive filesystems (Linux build servers) treat Project_Timeline.png
and project_timeline.png as different files. All-lowercase avoids broken image references when
the docs are built on a system other than the author's Windows machine.
13.2.3.1. Diagram Type Prefixes¶
DrawIO and similar diagram files often carry a short type prefix:
Prefix |
Meaning |
Example |
|---|---|---|
|
Block diagram |
|
|
Component diagram |
|
|
Interface diagram |
|
|
Sequence diagram |
|
Why: A _figures/ folder can grow large. The prefix groups related files together in
alphabetical listings and makes the purpose of a file clear before it is opened.
Note: The prefix is optional for single-topic pages where the folder already provides enough context.
13.2.4. Two Draw.io Formats for Two Directives¶
Draw.io diagrams exist in two forms depending on how they are embedded:
File format |
Directive |
When to use |
|---|---|---|
|
|
Static diagram; no interactive links needed |
|
|
Diagram with clickable navigation links embedded |
Why: The {drawio-figure} directive embeds the SVG inline in the HTML output, which preserves
hyperlinks drawn inside the diagram. The standard {figure} directive references an already-
exported SVG as an image — simpler but without interactivity.
Advantage: The distinction is explicit in the file name: .drawio.svg signals "exported,
static"; .drawio signals "source, live-rendered".
13.2.5. Section Labels¶
13.2.5.1. Underscores, Not Hyphens¶
Labels always use underscores:
(sec_introduction_and_goals)= ✓
(sec-introduction-and-goals)= ✗
Why: Sphinx resolves labels as Python identifiers internally. Underscores are unambiguous identifiers, while hyphens are parsed as a minus operator in some contexts. Underscores also visually separate labels from hyphenated prose words, making them easier to spot when scanning a file.
Note: Hyphens are valid MyST syntax and appear in older files in this repository. Both work — but within a single document, pick one and be consistent.
13.2.5.2. Standard Label Prefixes¶
Every label begins with a short prefix that identifies what kind of element it targets:
Prefix |
Used for |
Example |
|---|---|---|
|
Headings and sections |
|
|
Figures and diagrams |
|
|
Tables |
|
|
Code/text listings |
|
|
Inline definitions |
|
|
Product features |
|
|
Architectural enablers |
|
|
Appendix pages |
|
|
Process Assessment Model items |
|
|
Service pages |
|
Why: Without a prefix, a label like (lifecycle_concepts)= gives no hint whether it targets
a section, a figure, or a table. Prefixes let a reader understand a {ref} call without looking
up where the label is defined.
Advantage: Name collisions become unlikely — a section and a figure about the same topic can
coexist as sec_lifecycle_overview and fig_lifecycle_overview.
13.2.5.3. All Lowercase, English Words¶
Labels translate the heading into English, lower-cased, with underscores for spaces:
Heading (German) |
Label |
|---|---|
|
|
|
|
|
|
Why English: Labels are permanent identifiers. German headings change as content is updated; an English label derived from the meaning stays stable even if the German wording is refined. Cross-references scattered across the project do not need updating every time a heading is reworded.
13.2.5.4. Meeting-Minute Labels Encode the Calendar Week¶
(sec_2026CW23)=
# 2026 CW23
Sub-sections within a meeting minute use:
(sec_2026CW23_1_MON_architecture_review)=
## Monday — Architecture Review
Pattern: sec_YYYYCWNN_D_DAY_topic
Why: Meeting minutes are referenced from sprint notes, engineering notebooks, and decision records. A label derived from the date is stable (the meeting will always have happened on that week) and self-describing when it appears in a cross-reference.
13.2.6. Toctree Paths¶
Toctree entries omit the file extension and use paths relative to the current index.md:
```{toctree}
:maxdepth: 2
01-Introduction/index
02-Setup/index
03-Reference/index
```
Why no extension: Sphinx resolves .md and .rst automatically. Omitting the extension
means the toctree entry does not need updating if a page is converted from RST to Markdown (or
vice versa).
Why relative paths: Absolute paths would break if the folder is ever moved or if the docs are built from a different root. Relative paths are self-contained.
Alternative: When linking to a page in another section from a toctree (rare), use the path
relative to the project root with a leading slash: /12-Glossary/index.
13.2.7. {list-table} Instead of GFM Pipe Tables¶
All tables use the MyST {list-table} directive. GFM pipe syntax (| col | col |) is not used
for new content.
```{list-table}
:header-rows: 1
* - Version
- Change
- Reviewer
* - 1.0
- Initial release
- J. Smith
```
Why: GFM pipe tables break when cell content is long, contains inline markup, or spans
multiple lines. MyST {list-table} treats each cell as full Markdown, supports arbitrary content,
and renders consistently in HTML and PDF output.
Advantage: No more manual column-width alignment in the source. Cells can contain bullet
lists, code spans, or {ref} roles without escaping.
Alternative: GFM pipe tables are fine for very simple lookup tables (two or three short columns, plain text cells) where the visual alignment in the source is a readability win.
13.2.8. * as the Bullet Marker for Unordered Lists¶
Unordered list items use * (asterisk), not - (hyphen).
* System Engineering
* Software Engineering
* Hardware Engineering
Why: - is also used in YAML, {list-table} row markers, and task-list syntax. Using *
for plain bullets makes the difference visible at a glance and avoids accidental misparse.
Advantage: In a file that contains both {list-table} directives and regular bullet lists,
* bullets are immediately distinguishable from list-table row and cell markers.
Alternative: - is equally valid CommonMark. If a file already uses - consistently
throughout, changing it just for convention's sake adds noise to the diff.
13.2.9. Bilingual Headings with / Separator¶
Pages targeting both English and German readers use a slash separator in headings to show both language versions on a single line.
# Product Maturity Stages / Produktreifegrade
## Purpose / Zweck
Why: The handbook audience spans German-speaking engineers and English-speaking stakeholders. A single heading appears in the navigation tree, the page title, and search results — duplicating the page for each language would fragment cross-references and double the maintenance effort.
Advantage: Readers of either language recognise the heading immediately. The English term comes first and doubles as the canonical identifier for cross-references.
13.2.10. orphan: true for Pages Outside the Toctree¶
Any page that is not yet wired into a {toctree} should carry orphan: true in its frontmatter.
---
orphan: true
---
Why: Sphinx emits a warning for every .md file it finds that is not reachable from any
toctree. Without orphan: true, a page under active drafting pollutes the build log and may be
flagged as a CI failure.
Advantage: The build stays clean while the page is being written. The orphan: true flag also
signals to other authors that the page is a draft not yet integrated into the structure.
13.2.11. {todo} for Missing Content, Comments for Disabled Content¶
Two mechanisms exist for content that is not yet rendered — they serve different purposes.
{todo} — content that needs to be written:
```{todo}
Describe the release branching strategy.
```
Renders as a visible call-out in draft builds. Searchable. Can carry a title.
HTML comment — content that is drafted but temporarily hidden:
<!--
## Aufbau
This section will cover the structural overview once the diagram is finalised.
-->
Invisible in all output. Preserves intent for the next author.
Why the split: {todo} communicates a gap to reviewers and readers of the draft. An HTML
comment is appropriate when the content exists in some form but should not appear in any build
yet (e.g. a section disabled pending approval).
Advantage: Build tooling can count open {todo} items as a quality metric. HTML comments
accumulate silently and should be reviewed and either promoted or deleted when the surrounding
content matures.
13.2.12. User Abbreviations¶
Team members are referenced with {user} using short uppercase codes, typically three or four
letters derived from their name:
Written by {user}`AMAN`, {user}`FKR`, and {user}`MM`.
Real codes used in this project: AMAN, FKR, MM, KOO, TMOH, LPO, DWI, TCH,
JHH.
Why short codes: Full names change (spelling preferences, marriage, transliteration) and are
verbose in lists of attendees. Short codes are stable identifiers; the {user} role expands them
to a rendered display name and optional link.
Convention for new codes: Use the first letter of first name plus the first two letters of
the last name, capitalized (e.g. Alexander Mann-Wahrenberg → AMAN). If that collides, extend
to four characters.
13.2.13. Jira Ticket References¶
Reference Jira tickets inline with the {jira} role, never as a plain URL:
See {jira}`PJBIO-1060` for the full specification. ✓
See https://jira.vitronic.de/browse/PJBIO-1060 ✗
Why the role: The {jira} role produces a consistent link regardless of the Jira server URL.
If the Jira instance is migrated, only the role's base URL configuration needs updating, not every
individual reference in the documentation.
Project codes: Use PJBIO- for the primary Biomech project. Other project codes (e.g. CPQ-)
appear only when cross-referencing a dependency ticket in another project.
13.2.14. Language¶
Body text and headings are written in German. Technical identifiers — class names, method signatures, API paths, file names, configuration keys — stay in English regardless of surrounding language:
Die Klasse `PluginFactory` stellt die Methode `createPlugin(type)` bereit.
Der Endpunkt `/api/v2/viatars/{viatar_id}/crosssections` gibt ...
Why German for prose: The primary readership is the development team and stakeholders, who communicate in German. German prose avoids the awkward half-translated style that results from forcing technical documentation into a non-native language.
Why English for identifiers: Source code, API contracts, and configuration files are in English. Copying an identifier verbatim from the code into the documentation and back into the code must be lossless. Translating identifiers would create a gap between the documentation and the system it describes.
Section labels and file names are always English — see the respective sections above.