Manual of Style: Difference between revisions

<strong>This Manual of Style</strong> (hereinafter referred to as <strong>"MoS"</strong> or <strong>"MOS"</strong>) is designed to ensure that all content on the NixOS Wiki is presented in a clear and consistent  manner. It provides guidelines on language usage, article structure, formatting, and other stylistic elements to maintain a high standard of quality across the wiki. This guide is intended for all contributors, whether they are new to editing or have extensive experience, to assist them in creating content that is both informative and accessible.

Any new content incorporated into this page must directly address a persistently recurring style issue.

=== Plagiarizing ===

* <strong>Definition:</strong> Plagiarism includes copying text, images, or other media without crediting the original source.

* <strong>Consequences:</strong> Plagiarized content will be removed immediately. Contributors who repeatedly plagiarize may be banned.

=== Vandalism ===

Vandalism refers to any act of deliberately adding false or misleading information, deleting content, or otherwise compromising the integrity of the wiki.

* <strong>Response:</strong> Vandalized pages will be promptly reverted to their previous state. Persistent vandals will be blocked from editing.

* <strong>Reporting:</strong> Users are encouraged to report vandalism immediately.  

Spamming and advertising are prohibited to keep the wiki free from clutter and irrelevant content.

* <strong>Action:</strong> Spammers will have their content removed and may be banned from editing. Legitimate contributions should not include promotional content.

Hostility towards other wikis is not tolerated. Editors who make hostile comments about other wikis will be warned and may be blocked.

== Article titles, headings, and sections ==

=== Article titles ===

* <strong>Consistency:</strong> Ensure that article titles are consistent with the titles of related content to maintain a cohesive structure across the wiki.

Proper section organization is crucial for creating well-structured, easily navigable articles. A logical and consistent structure helps readers find information quickly and understand the content more effectively.

* Use a clear hierarchy of headings to organize content:

* Arrange sections in a logical order, typically following this pattern:

   2. Installation

   3. Configuration

   5. Troubleshooting

For consistency across the wiki, use the following structure where applicable:

== Installation ==

== Configuration ==

==== Advanced ====

== Troubleshooting ==

== References ==

While consistency is important, remember that different topics may require different structures. Use your judgment to adapt the standard structure when necessary, always prioritizing clarity for the reader.

Section headers should be concise and accurately reflect the content of the section. They should provide a clear indication of what the reader can expect to find in that section.

* <strong>Consistency:</strong> Maintain consistency in the formatting and style of section headers throughout the article.

Be mindful of length restrictions when crafting titles and section headings. Excessively long names can make navigation difficult and negatively impact readability.

* <strong>Conciseness:</strong> Strive for brevity without sacrificing clarity. Consider rephrasing complex ideas or breaking them down into multiple sections.

* <strong>Articles, blog posts, and short stories:</strong> Use double quotation marks

* <strong>Software names, tools, and commands:</strong> Use regular text, typically with initial capitalization

* <strong>Short quotes (less than 40 words):</strong> Use double quotation marks ("") and incorporate into the text.

* <strong>Long quotes (40 words or more):</strong> Use block quotes by indenting the entire quote or using the <strong>blockquote</strong> tag.

Proper capitalization improves readability and maintains a professional appearance:

* <strong>Section headers:</strong>

** Subsections (===, ====): Use sentence case

* <strong>Proper nouns:</strong> Always capitalize names of specific people, places, organizations, and NixOS-specific components.

* <strong>Common nouns:</strong> Do not capitalize unless they are part of an official name or at the beginning of a sentence.

* <strong>Acronyms and initialisms:</strong> Generally use all caps, but follow official styling if different.

** Use numerals for 10 and above.

** Use commas for numbers with four or more digits (e.g., 1,000, 10,000).

** For very large numbers, consider using words (e.g., 1 million instead of 1,000,000).

** Include the time zone when relevant (e.g., 14:30 UTC).

==== Abbreviations ====

When using these terms:

* Be consistent in capitalization (e.g., always "NixOS", never "Nixos" or "NIXOS").

* Use the full term on first mention, followed by any abbreviation in parentheses if it will be used later.

* Use double square brackets to create a wikilink: <syntaxhighlight lang="mediawiki">[[Page Name]]</syntaxhighlight>

* If the link text should differ from the page name, use a pipe character: <syntaxhighlight lang="mediawiki">[[Page Name|displayed text]]</syntaxhighlight>

==== External linking ====

Proper image file naming helps with organization and searchability:

* '''Lowercase:''' Use lowercase letters to avoid case-sensitivity issues.

* '''Hyphens:''' Use hyphens (-) to separate words, not underscores or spaces.

* <strong>Relevance:</strong> Only include videos that directly support the article's content.

* <strong>Permissions:</strong> Ensure you have the right to use and link the video content.

* <strong>Captions:</strong> Include a descriptive caption below the video.

| Row 2, Cell 1 || Row 2, Cell 2 || Row 2, Cell 3

|}

</syntaxhighlight>

Translating wiki content is crucial for making information accessible to a global audience. Proper translation not only conveys information accurately but also respects cultural nuances.

* <strong>Accuracy:</strong> Strive for translations that faithfully represent the original content without altering meaning or omitting information.

* <strong>Clarity:</strong> Prioritize clear, understandable language over literal translations.

* <strong>Consistency:</strong> Maintain consistent terminology and style across all translated pages.

==== Preparation ====

==== Translation ====

* Maintain a separate page for language-specific translation guidelines.

* Provide guidance on translating or adapting idiomatic expressions.

* <strong>Commands:</strong> Keep command syntax unchanged, but translate descriptions and explanations.

* <strong>Categories:</strong> Create and use translated category names.

* Regularly review and update translations to ensure they remain accurate and up-to-date.

== Templates ==

=== Common templates ===