OSDev Wiki:Manual Of Style

From OSDev Wiki
Jump to: navigation, search

This page is a guideline for those writing new articles or contributing to existing ones. Being a guideline, these rules are in no case binding, though we expect that the articles follows the concepts as appropriate. Hence these rules can be overridden by common sense.

Contents

Article Naming Conventions

  • Titles start with a capital letter (as if it were the start of a sentence)
  • Words are separated with spaces, each new word starting with another capital
  • Further capitalizing and use of non-character symbols is to be done according to the English language.

examples:

  • kbc commands -> KBC Commands
  • gcc cross compiler -> GCC Cross-Compiler

bad titles:

  • hardware (rule 1: should start with a capital: Hardware)
  • FileSystems (rule 2: words are separated with spaces: should be File Systems)
  • Cpuid (rule 3: The Intel manual defines this in all-caps: should be CPUID)


Article Contents

Articles should be informative in style. FAQ style is discouraged. Tutorials are allowed, but try to keep instructional content separate from enyclopedic content.

Code Snippets

Code snippets can be used on any page where useful.

Code snippets should be readable and understandable:

  • Proper identation: little trouble for a largely increased readability. Things like whether you put your {}'s on the same line or on the next is subject to your taste
  • Avoid long lines: these break the layout as well as making things very difficult to read. 40 characters should be fine.
  • Comments: Use common sense. Short snippets might not need any, longer ones are more likely. Assembly code can in general use more comments than higher level languages.
  • Language: The preferred language is either C or Assembly, as most programmers know these. Try however to minimize mixing of languages (inline assembly).

Code blocks can be marked with a leading space in front of each line or by using the pre tags. However, the wiki supports the source tags, which are preferred since they provide syntax highlighting for several languages.

// C code formatted using pre tags.
int main(void)
{
    return 0;
}
// C code formatted using source tags with lang="c".
int main(void)
{
    return 0;
}

Tables

Tables should be created like this:

{| {{wikitable}}
! Header 1
! Header 2
|-
| Value 1 || Othervalue 1.1
|-
| Value 2 || Othervalue 2.1
|-
| rowspan="2" | Value 3 || Othervalue 3.1
|-
| Othervalue 3.2
|}

The table will look like this:

Header 1 Header 2
Value 1 Othervalue 1.1
Value 2 Othervalue 2.1
Value 3 Othervalue 3.1
Othervalue 3.2

Additionally you can use the {{Yes}} and {{No}} for comparison tables. You can create notes in tables with the following codes (the first to insert a reference, the second is the reference text):

<sup>[[#Note1|1]]</sup>

<small id="Note1">Note 1: Some description here.</small>

Sections with additional info

The layout of additional info sections should be like this:

== See Also ==

=== Articles ===
* [[Some Article]]
* ...

=== Threads ===
* [[Topic:18304|Name of forum thread]] - Write what you'll find in the thread here
* ...

=== External Links ===
* [[wikipedia:Operating system|Operating system]] on Wikipedia
* [http://www.osdever.net/ Name of homepage] - Write what you'll find on the homepage
* ...

Discussing articles

Issues that might need a discussion should be posted on the talk backpages. when you do, please use four tildes to sign your message: ~~~~

More important issues should be posted on the wiki forum, as well anything not directly related to any single article, as these are checked by more people.


Sandbox

Each member has his own userpage, in which he is free to try things as needed. Please try to minimize Category:xxx links as they cause links to appear to your article. You can link to a category by inserting a colon in the beginning of the wikilink like this: [[:Category:Tutorials]].

You can have a look at some other people's user pages for ideas.

Discussing the Manual of Style

To request changes, please post a message to the Manual of Style thread

Personal tools
Variants
Actions
Navigation
About
Toolbox