Style guidelines

1. Content guide

The style guide will always leave some leeway, since there is no single best way of doing something, but the overall style should be consistent within an article and may be different across articles. This also means one should keep the current style when expanding an article. An article’s style should only be changed when there is good reason to.

Note	Inconsistent styling within an article might cause confusion to the reader, however imposing one arbitrary decision across the entire wiki will be cumbersome and will be of limited use. In addition, different topics may require different treatment.

An article should be structured as follows:

Warning templates

Note
This is the first thing any reader should see.

Lead section (a short, self-contained overview of the topic)

Note	A reader should be able to get a quick overview of the topic without reading a long text. A person encountering the article should be able to assess quickly, if they are interested in reading it further or not. The lead section is also the part displayed in search engines and social media embeds.

Main matter
See also (internal links to tangentially related topics that might be of interest to the reader, in order to facilitate navigation)

Note
The reader will be able to easily find articles they want to read next.
Further reading (external links, books, etc …, such as tutorials, references, and documentation, that might be of interest to someone writing an OS)

Note
The wiki cannot and should not cover everything, it serves as a starting point for further research.
References (list of inline citations that appear as footnotes throughout the article)

American English spelling and terminology used in technical literature should be used when writing articles. However, terms that are widely used across all English-speaking countries should be preferred over terms used exclusively in the US.

Note
Most technical literature is written in American English.
An article should be logically divided into sections and subsections.

Note
It facilitates navigation of long articles. Sections may appear in search engine results.
- Article and section titles should be written in sentence case (first letter of first word capitalized) and should not contain redundant "the" or "a". This means "BIOS", not "The BIOS". Exception: proper names.
- A subsection title should not redundantly contain the title of its parent section.
  
  Note
  Do not repeat yourself.
- Avoid markup in article and section titles.
  
  Note
  They appear in cross-references, tables of contents and search engine results. Use of certain markup may cause unforeseen problems.
Every claim in an article should be sourced, preferably using inline footnotes. Primary sources (official documentation, references or specifications) should be preferred over secondary ones, unless primary sources are not available or have errors.

Note
The reader should be able to easily verify the correctness of content. Factual errors and hearsay should also be avoided.
- Claims in the lead section must not have an inline citation, if they appear in the main matter.
  
  Note
  Do not repeat yourself.
Articles should have a neutral point of view. They should not prefer a certain solution over another one, when the alternative is also widely used (avoid holy wars). However, arguments for and against a solution may be presented in an objective and sourced way.
- If opinions must be included, they must be quoted from a source.
  
  Note
  The wiki is not a place for holy wars. Different people have different opinions and there is no objective way to settle all disputes.
- Modern methods and solutions should be emphasized over obsolete ones. This does not mean that older technologies are not covered. However, the reader must always be aware of legacy.
  
  Note
  This wiki should focus on modern OS development.
If the title of an article is mentioned in another article, the first mention of that title should be linked.

Note
Navigation in any wiki lives from internal links. However, articles should not be cluttered with internal links.
- If a link to an article exists in the lead section, another link may exist in the main matter.
- An article may be linked more than once within a long article, but not more than once within the same section.
  
  Note
  The one link guideline should not get in the way of navigability.

Code examples should be small self-contained snippets of code (as a rule of thumb, not larger than a screen). Articles should not be written as step-by-step tutorials.

Note

OS development requires a certain level of skill. This includes being able to implement code based on a specification. Providing large and complete code examples gives novice programmers the incentive to simply copy and paste them, without fully understanding them. OS development is not a linear process and there are a lot of choices that have to be made. Tutorials cannot cover the broadness of OS development. Large code examples are also harder to test and maintain. Buggy code should not be in the wiki.

Code examples should be written in C. However, they must not be completely valid source files. For example, functions may be used that are not declared anywhere in the code snippet. Snippets should be vague and generic and should have pseudocode-like qualities.

Note	C is the lingua franca of programming languages and the generic programming language. It is known by most programmers. In addition, it is a simple language that does not contain a lot of features that some programmers might not know.

An exception to the C rule is low level code that must be written in assembly. Assembly is architecture-specific and therefore should be used only on architecture-specific pages or sections. When it comes to x86 assembly, the most convenient syntax (Intel or AT&T) in the relevant context should be used.

Articles should be written in proper English with encyclopedic tone. A list of common things to look out for is provided. No rationale is provided, since these are common rules of English and are essentially linguistic conventions.
- General rules, grammar, tone and vocabulary
  - Avoid repeating yourself. Avoid redundant phrases in sentences. Avoid long run-on sentences. For example, "OS development requires a certain level of skill" is preferred over "OS development requires the programmer to have a certain level of general skill".
  - Articles should be written in encyclopedic tone, this includes never using the first or second person ("I", "me", "you"), unless quoting.
  - "The" should never be capitalized mid-sentence, unless it is part of a proper name.
  - Plural forms of nouns are formed by using -s or -es, not -'s.
  - Possessive forms of nouns are formed by using -'s.
    
    Important
    "It" is not a noun, but a personal pronoun. The corresponding possessive pronoun is "its", not "it’s".
  - Use the present tense by default.
  - Avoid contractions like "can’t" or "don’t".
  - Avoid language like "note", "remember" or "obviously", which either address the reader directly or makes presumptions about the reader’s knowledge.
  - Use gender-neutral language, avoid the use of "he" or "she".
  - Abbreviations may be used in article or section titles, if they are used more commonly than the full expression (for example "BIOS" instead of "Basic Input/Output System").
  - The first occurrence of an abbreviation must be written out, with the abbreviation following in parentheses: "Basic Input/Output System (BIOS)".
  - Abbreviations may or may not include full stops, however no spaces may exist within the abbreviation ("B.I.O.S." is allowed, but "B. I. O. S." is not). However their use must be consistent and must follow conventions set in technical literature (use "BIOS", not "B.I.O.S.").
- Punctuation and symbols
  - Do not use ampersands (&), use "and", unless quoting or part of a proper name like "AT&T".
  - Use boldface to highlight an important term being introduced (such as the first occurrence of the article title), but do not use it more than once for the same term. For emphasis and foreign words, use italics. Do not italicize or boldface nearby punctuation.
  - When quoting a source, the source must be mentioned in the text, in addition to having a footnote as reference.
  - Straight quotes (") and apostrophes (') should be used (no curly quotes or apostrophes, no backticks, no low-high quotes, no guillemet).
  - Nested quotes should use alternating quotes and apostrophes.
  - Quotations should change the original text only minimally, any omitted, added, or changed words should be enclosed in square brackets.
  - A comma before a quotation can be omitted, if the sentence is still grammatically correct and if the meaning of the quote is not changed.
  - Punctuation may be included inside a quotation, if it makes logical sense and the punctuation is present in the original text. If isolated fragments of a sentence are quoted, nearby punctuation should usually be outside of the quote.
  - An ellipsis consists of three dot characters (…) without spaces. They should be used when content is omitted from quotes. Square brackets may be placed around them to indicate that they are not part of the original quote.
  - The main text may include side notes or clarifications in parentheses. However, the text around the parentheses must still make grammatical and logical sense without the content inside the parentheses.
  - Nested parentheses should be avoided. Adjacent set of parentheses should also be avoided, the phrases should be joined by a comma. This means "the BIOS (a type of firmware) (replaced by UEFI)" is not allowed, and should be replaced by "the BIOS (a type of interface, replaced by UEFI)".
  - Semicolons may be used to join two phrases that could stand as independent sentences: "stivale2 can load a kernel in long mode; multiboot cannot". Phrases that cannot stand alone may not be joined with a semicolon.
  - Hyphens should be used to link prefixes ("quasi-multipliers") and compound modifiers ("well-known").
  - Dashes may be used to punctuate a sentence, in order to indicate that the two surrounding phrases indicate a pair. They should be used sparingly.
  - Never put a space before punctuation.
- Dates and numbers
  - Months and days of week are upper case, while seasons are lower case ("Monday", "July", "summer").
  - Either use 12-hour ("2:45 pm" or "2:45 p.m.") or 24-hour dates ("14:45"). Avoid "12 am" and "12 pm", when using the 12-hour format. Rather, use "noon" or "midnight". The latter is ambiguous, so specify whether it is the beginning or the end of the day. The 24-hour format has no such ambiguity "0:00" is the beginning of the day and "24:00" the end.
  - Dates are either written as "19 December 2021" or "December 19, 2021". Numerical dates may be written in the yyyy-mm-dd format: "2021-12-19".
  - When omitting the year write either "19 December" or "December 19".
  - When referring to months, use "December 2021". You may use abbreviations like "Dec", if the space is limited.
  - Avoid "#", use "No.", "Nos." or "number".
- List items should be formatted consistently and follow a certain "schema", such as being all complete sentences, sentence fragments or names. Mixing of different types of items should not occur.
It is important to note that these are guidelines. They apply in the vast majority of cases, but there may be some rare exceptions. Exceptions should be introduced with care and with a good rationale.

Note
Not every edge case can be reasonably covered.

2. AsciiDoc and source code style

As much as we strive for clean content, we should strive for clean source code. The following guidelines will help ensure future contributors and/or editors of the wiki have no problems making changes.

2.1. AsciiDoc formatting guidelines

For an AsciiDoc reference, please see the AsciiDoc Syntax Quick reference as well as the more broad AsciiDoc Language Documentation.

A useful tool for formatting your AsciiDoc is par, although, as it is not specific to AsciiDoc, it will break formatting elements. Use sparingly and explicitly, on ranges of text.

Full stops are line breaks

AsciiDoc does not care about line breaks, only paragraph breaks. By breaking lines on full stops, we minimize the chance of inducing conflicts with future contributors to the same page, but different parts. par violates this rule, so it is best to reformat a paragraph, break on full stops, and then rejoin lines to fit.

1
2
3
4 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat.

Long lines should be broken

Long lines in the source code are hard to read. If your AsciiDoc sources include lines longer than 100 columns (including leading whitespace, for simplicity sake), hard wrap them. Many text editors can do this out of the box for you.

Links to other bits of AsciiDoc should be xrefs

xref macros should be used to connect contents on the wiki. For this reason, please be careful when removing sections or IDs, at least until stronger verification is introduced.

Referenced sections should always have explicit IDs

For the sake of preventing issues induced by cross references, and for the sake of clarity, all cross references must be made to explicit anchors.

1
2
3
4 See <<section_1>>.

[#section_1]
== Section 1

Leave comments for further editors

AsciiDoc supports comments. When something is not immediately obvious, or when something is left out, add a comment attributed to yourself. These should be in the format of // TYPE(author): text. TYPE should be TODO, XXX, FIXME, NOTE, etc. Please note that comments also tend to go stale, so their overuse is strongly discouraged.

1
2
3
4
5
6 // TODO(arsen): add xref validation

////
NOTE(steve): This paragraph is quite noteworthy!
             I should talk about it in more detail.
////

Align text elements, use 2-space indent

On text elements such as lists, align continuation lines (and in turn sentences) to the start of the text on the first line of the element. Indentation, for instance when writing definition lists, should be done in two space increments. We are dealing with text, not code; text is much more dense.

Exception: places where syntax makes it impossible to do otherwise.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11 . This first example demonstrates how to indent continuations.
  Isn't this lovely?

. This example is wrong.
Some would even consider it unintuitive.

Indentation::
  The blank space produced by indenting, often used for clarity of scope
+
Sadly, to insert a newline above this line, we must lose indentation here as to
not make this paragraph verbatim.

2.2. C source code formatting

As established, C is the lingua franca of programming, all code that is not platform-specific assembly should be written in C, with placeholders for platform details (e.g. port I/O). Here are a few guidelines on C code:

Do not assume a compiler. If absolutely necessary, assume the common subset of Clang and GCC.

Exception: compiler-specific pages.

Format code in the One True Brace Style.

This style is a variant of K&R with optional braces explicitly stated, and opening braces of blocks on the same line as their respective statements. Crucially, adding a line of code should never result in editing another line (e.g. to add a brace) or result in flow that disagrees with indentation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20 /* bad */
f1(int a, int b, int c)
{
  if (a)
  {
    return b + c;
  }
  else {
    return a * c;
  }
}

/* good */
int f1(int a, int b, int c) {
    if (a) {
      return b + c;
    } else {
      return a * c;
    }
}

The unit of indentation is four spaces, and alignment is allowed.

1
2
3
4
5 int function1(int a, /* carried over for demonstration sake */
              int b,
              int c) {
    /* ... */
}

Use a snake_case naming convention, with names up to around 16 characters.

While modern compilers are able to handle more, over-verbose function names will lead to less readable code on the wiki. Since code on the wiki should be considered pseudo-C and incomplete, there is no need to worry about function names conflicting, and hence no need to introduce namespacing (i.e. whatever_ prefixes).

3. Hard rules

These rules must not and cannot be broken under any conditions. Violations of these rules will not be accepted under any circumstance.

Absolutely no copyright violation. By submitting a contribution to this wiki, you irrevocably agree to release your contribution under the CC0 license and certify that you have the right to do so.
Commit messages must conform with the Conventional Commits standard.
- The following list contains some commit types that may be used:
  - deletion: removal of a wiki article.
  - expansion: expansion of a wiki article.
  - fix: a minor fix that does not change the essence of the thing being changed (applies to all sections of the wiki).
  - feat: introduction of a new feature (does not apply to edits of wiki articles).
  - generator: changes to files related to site generation, other than CI.
  - new: creation of a new wiki article.
  - ref: changes to references.
  - style: changes related to code or markup style, without changing the meaning of the code or markup itself.
  - trim: partial removal of content form a wiki article.
- Commits should also contain a scope indicating what part of the repository has been changed:
  - ci: changes related to CI.
  - content: content articles of the wiki (i.e. articles about OSDev).
  - css: CSS files in the css folder.
  - generator: files related to the site generator.
  - html: HTML files in the html folder.
  - static: assets that go in the static folder.
  - meta: articles in the wiki, related to rules and governance (i.e. articles with the category Meta).
  - misc: other miscellaneous files.
- Commits changing articles should usually modify a single article, however frequent exceptions are allowed, especially for commits of the type fix and style. In case a single article is changed, the slug (i.e. filename without the filename extension) of the article must be listed as the scope of the commit. In case multiple articles, that are all members of a certain category or tag, are modified, that tag or category may be modified.
- The description of the commit must summarize all changes; descriptions must not be vague (e.g. "updated bios.adoc").