Manual of Style

⚠

Under construction!

✦

Editors are generally expected to adhere to this standard, applying common sense and allowing for occasional exceptions. Significant edits to this page should reflect a consensus. If uncertain, please discuss on the talk page first.

This Manual of Style (hereinafter referred to as "MoS" or "MOS") 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.

Editors are expected to compose articles using language that is clear, concise, and readily comprehensible. Articles must be organized with consistent, reader-friendly layouts and formatting, as delineated in this guide.

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

Rules of Thumb

• Use Common Sense: Always apply logic and reason when contributing to the wiki.
• Cite Reliable Sources: Ensure that all information added is verifiable and sourced from reliable references.
• Maintain Neutrality: Strive to present information in a neutral and unbiased manner.
• Be Clear and Concise: Use clear, concise, and grammatically correct language to ensure readability and understanding.
• Follow Site Guidelines: Adhere to the site's guidelines and policies at all times.
• Avoid Edit Wars: Engage in constructive discussions to resolve content disputes rather than engaging in edit wars.
• Protect Privacy: Do not share personal information about yourself or others without consent.
• Contribute Constructively: Aim to improve the quality of the content and the overall user experience.
• Use Proper Formatting: Follow the wiki's formatting guidelines to ensure consistency and readability.
• Stay On Topic: Ensure that contributions are relevant to the subject matter of the page.
• Report Issues: Report any issues or inappropriate behavior to the administrators promptly.
• Be Patient and Helpful: Assist new users and be patient with those who are still learning the ropes.
• Respect Others: Treat all users with respect and courtesy. Personal attacks and harassment are strictly prohibited.
• No Advertising, Vandalism, or Spamming: Contributions should be constructive and relevant. Any form of advertising, vandalism, or spamming will not be tolerated.

Content Policy

Plagiarizing

Plagiarizing involves using someone else’s work without proper attribution and presenting it as your own. This practice is strictly prohibited on this wiki.

• Definition: Plagiarism includes copying text, images, or other media without crediting the original source.
• Consequences: Plagiarized content will be removed immediately. Contributors who repeatedly plagiarize may be banned.
• Prevention: Always cite your sources. Use quotation marks for direct quotes and provide proper references.

Vandalism

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

• Types of Vandalism: This includes adding false information, deleting pages, inserting inappropriate content, and spamming links.
• Response: Vandalized pages will be promptly reverted to their previous state. Persistent vandals will be blocked from editing.
• Reporting: Users are encouraged to report vandalism immediately.

Spam and Advertisement

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

• Definition: Spam includes repetitive content, irrelevant links, and advertisements for external products or services.
• Detection: Automated filters and manual reviews help identify and remove spam.
• Action: Spammers will have their content removed and may be banned from editing. Legitimate contributions should not include promotional content.

Unofficial Wikis

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

• Linking to Other Wikis: Linking to other wikis is not prohibited if such links contribute to the quality of the content.
• Contribution Recommendation: It is recommended that editors only contribute to one wiki at a time to ensure they do not inadvertently violate the copyright policies of the wikis they edit.

Article titles, headings, and sections

Article titles and section headings should reflect the content they contain. Titles and section headings should be concise and precise. Titles should be consistent with the titles of related content.

Article titles

Article titles should be clear and descriptive, providing a succinct summary of the article's content. Avoid using jargon or overly technical terms unless they are widely understood within the context of the wiki. Titles should be formatted in title case, capitalizing the first letter of each major word.

• Consistency: Ensure that article titles are consistent with the titles of related content to maintain a cohesive structure across the wiki.
• Avoid Redundancy: Do not include unnecessary words or phrases that do not add value to the title.

Section Organization

Sections within an article should be organized logically to guide the reader through the content in a coherent manner. Each section should cover a distinct aspect of the topic, and related sections should be grouped together.

• Hierarchy: Use a clear hierarchy of headings (e.g., ==, ===, ====) to indicate the structure of the content. Main sections should use level 2 headings (==), while subsections should use level 3 (===) and level 4 (====) headings as needed.
• Flow: Arrange sections in a logical order, starting with an introduction and moving through the main points before concluding.

e.g. Where applicable, you must use the following structure:

(Description)

== Installation ==
├── ==== Using nix-shell ====
├── ==== Using Global Configuration ====
└── ==== Using Home Configuration ====

== Configuration ==
├── ==== Basic ====
└── ==== Advanced ====

== Tips and Tricks ==
└── ==== Location of Options ====

== Troubleshooting ==
└── ==== Issue 1 ====

== References ==

Section Headers

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.

• Clarity: Use clear and descriptive language for section headers. Avoid vague or ambiguous terms.
• Consistency: Maintain consistency in the formatting and style of section headers throughout the article.

Length Restrictions

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

• Limit Characters: Section headings should ideally remain under 40 characters.
• Conciseness: Strive for brevity without sacrificing clarity. Consider rephrasing complex ideas or breaking them down into multiple sections.

Text formatting

Proper text formatting is essential for maintaining consistency, readability, and professionalism across the NixOS Wiki. This section outlines the guidelines for various text formatting elements to ensure a uniform presentation of information.

Title of works

When referencing titles of various works, follow these guidelines:

• Articles, blog posts, and short stories: Use double quotation marks
  • Example: "Understanding Nix Flakes", "The NixOS Installation Guide"

• Software names, tools, and commands: Use regular text, typically with initial capitalization
  • Example: Nix, NixOS, nixpkgs, nix-shell

• Website names: Use regular text without quotes or italics
  • Example: Visit the NixOS website for more information.

When in doubt, prioritize clarity and consistency within the article.

Quotations

Proper quotation formatting helps distinguish cited material from original content:

• Short quotes (less than 40 words): Use double quotation marks ("") and incorporate into the text.
  • Example: According to the documentation, "NixOS is a Linux distribution built on top of the Nix package manager."

• Long quotes (40 words or more): Use block quotes by indenting the entire quote or using the blockquote tag.

• Quotes within quotes: Use single quotation marks (') for the inner quote.
  • Example: "The developer explained, 'Nix provides a purely functional approach to package management,' which revolutionized the field."

• Citations: Always provide a source for quotations, either inline or as a footnote.
  • Example: "NixOS offers reproducible builds"[1].

• Alterations and omissions: Use square brackets [] to indicate changes or additions to quotes, and ellipsis (...) for omissions.
  • Example: "NixOS [provides] a unique approach to ... configuration management."

Capital letters

Proper capitalization improves readability and maintains a professional appearance:

• Article titles: Use title case, capitalizing all major words.
  • Example: Installing NixOS on a Virtual Machine

• Section headers:
  • Main sections (==): Use title case
  • Subsections (===, ====): Use sentence case
  • Example:
    • Installation Process
    • Preparing the installation media

• Proper nouns: Always capitalize names of specific people, places, organizations, and NixOS-specific components.
  • Example: Nix, NixOS, Nixpkgs, Eelco Dolstra

• Common nouns: Do not capitalize unless they are part of an official name or at the beginning of a sentence.
  • Example: "The package manager is efficient." but "Nix Package Manager"

• Acronyms and initialisms: Generally use all caps, but follow official styling if different.
  • Example: RAM, CPU, NixOS (not NIXOS)

Boldface

Use bold text sparingly to emphasize important information:

• First mention: Bold the first occurrence of the article's main topic in the introduction.
  • Example: <strong>NixOS</strong> is a Linux distribution built on top of the Nix package manager.

• Key terms: Use bold for important terms being defined.
  • Example: A '''derivation''' in Nix is a description of how to build a package.

• User interface elements: Bold names of buttons, menu items, or other UI elements.
  • Example: Click the Save button to apply your changes.

• Avoid overuse: Do not use bold for entire sentences or paragraphs, as this reduces its effectiveness.

Italic

Italic text serves several purposes in technical writing:

• Emphasis: Use italics to stress particular words when appropriate.
  • Example: It is crucial to back up your configuration before making major changes.

• Non-English words: Italicize words or phrases from languages other than the primary language of the article.
  • Example: In programming, we often use the term de facto to describe widely accepted standards.

• Do not italicize: Proper names, technical terms after their first use, or entire paragraphs.

Spacing

Consistent spacing enhances readability and maintains a clean appearance:

• Single space after periods: Use only one space after a period at the end of a sentence.

• No spaces around slashes: In constructions like "and/or" or "TCP/IP", do not add spaces around the slash.

• Space after commas: Always include a space after a comma, but not before.

• Lists: Add a space after the list marker (*, #) in bulleted or numbered lists.

• Parentheses: No spaces inside parentheses, but do use spaces outside when in a sentence.
  • Example: NixOS (a Linux distribution) offers many advantages.

• Code blocks: Use consistent indentation within code blocks for readability.

Numbers and dates

Consistent formatting of numbers and dates is crucial for clarity:

• Numbers:
  • Spell out numbers zero through nine in prose.
  • 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).

• Percentages: Use the % symbol with numerals (e.g., 50%), but spell out "percent" when the number is also spelled out (e.g., five percent).

• Dates:
  • Use the format: Month Day, Year (e.g., January 1, 2024).
  • For numeric dates, use ISO 8601 format: YYYY-MM-DD (e.g., 2024-01-01).

• Time:
  • Use 24-hour clock format to avoid ambiguity (e.g., 14:30 instead of 2:30 PM).
  • Include the time zone when relevant (e.g., 14:30 UTC).

• Versions:
  • Do not add software versions, since they are prone to change.

Abbreviations

Proper use of abbreviations ensures clarity while maintaining brevity:

• First use: When first using an abbreviation, write out the full term followed by the abbreviation in parentheses.
  • Example: The Nix Expression Language (NEL) is used to define packages.

• Common abbreviations: Well-known abbreviations (e.g., RAM, CPU) don't need to be spelled out on first use.

• Plurals of abbreviations: Add 's' without an apostrophe (e.g., SSDs, not SSD's).

• Periods in abbreviations:
  • Generally, omit periods in abbreviations (e.g., PhD, AM/PM).
  • Use periods for lowercase abbreviations (e.g., i.e., etc.).

• Units of measurement: Use standard abbreviations without periods (e.g., 5 GB, 10 MHz).

Grammar and punctuation

Correct grammar and punctuation are essential for clear communication:

• Comma usage:
  • Use the Oxford comma in lists of three or more items.

• Semicolons: Use to separate closely related independent clauses or in complex lists.

• Colons: Use to introduce lists or explanations.

• Hyphens and dashes:
  • Use hyphens (-) for compound modifiers (e.g., well-known package).
  • Use en dashes (–) for ranges (e.g., 5–10 minutes).
  • Use em dashes (—) for parenthetical thoughts—like this one—in sentences.

• Parentheses: Use sparingly to include additional information without disrupting the flow of the sentence.

• Quotation marks: Place periods and commas inside quotation marks. Place other punctuation outside unless it's part of the quoted material.

• Active voice: Prefer active voice over passive voice for clearer, more direct writing.

Wording and tone

Maintain a consistent and appropriate tone throughout the wiki:

• Formal but approachable: Strike a balance between professional and friendly.

• Clarity: Use clear, concise language. Avoid jargon unless necessary, and explain technical terms.

• Objectivity: Present information neutrally, avoiding bias or personal opinions.

• Consistency: Maintain consistent terminology throughout articles and across the wiki.

• International audience: Consider that readers may not be native English speakers. Avoid colloquialisms or culture-specific references.

• Direct address: Use "you" to address the reader directly when providing instructions or explanations.

Common examples of tone

Here are some examples of appropriate and inappropriate tone:

• Appropriate: "To install NixOS, follow these steps carefully."
• Inappropriate: "Installing NixOS is super easy! Here's how to do it."

• Appropriate: "If you encounter an error, consult the troubleshooting section."
• Inappropriate: "If you get an error, check the solution below!"

Remember, the goal is to provide clear, helpful information in a professional manner.

Images

Images can greatly enhance the content of wiki articles. When using images, follow these guidelines:

• File types: Use PNG for screenshots and diagrams, JPEG for photographs, and SVG for logos and icons when available.
• Size: Keep file sizes reasonable. Aim for under 1MB for most images.
• Alt text: Always provide descriptive alt text for accessibility.
• Captions: Use clear, concise captions to describe the image content.
• Alignment: Generally, align images to the right of text unless a different alignment better serves the content.

To add an image:

[[File:Example.png|thumb|right|250px|Alt text: Description of image content]]

Image file names

Proper image file naming helps with organization and searchability:

• Descriptive names: Use clear, descriptive file names (e.g., "NixOS-installation-partitioning.png").
• Lowercase: Use lowercase letters to avoid case-sensitivity issues.
• Hyphens: Use hyphens (-) to separate words, not underscores or spaces.
• Avoid special characters: Stick to alphanumeric characters and hyphens.
• Version numbers: If updating an image, consider adding a version number (e.g., "nixos-logo-v2.svg").

Examples of good file names:

• nixos-boot-screen.png
• package-management-diagram.svg
• user-home-directory-structure.jpg

Copyrighted material

Respecting copyright is crucial. Follow these guidelines when dealing with copyrighted content:

• Permission: Always obtain permission before using copyrighted material.
• Fair use: If claiming fair use, clearly state this and provide a rationale.
• Attribution: Properly attribute all copyrighted material to its source.
• Licenses: Use content with compatible licenses (e.g., Creative Commons).
• Public domain: Clearly mark content that is in the public domain.

To attribute copyrighted material:

{{Attribution
 | author = Original Author
 | source = https://example.com/original-source
 | license = CC BY-SA 4.0
}}

✦

This template does not yet exist! Remove this note if added.

Note: When in doubt about the copyright status of material, do not use it. It's better to err on the side of caution.

Videos

Videos can be a valuable addition to wiki articles, especially for tutorials or demonstrations. Follow these guidelines:

...

Translation

Translation of content is essential to make the wiki accessible to a broader audience. Accurate and culturally sensitive translations help ensure that information is available to users who speak different languages.

• Accuracy: Translations should be accurate and faithful to the original content. Avoid adding or omitting information that could alter the meaning.
• Cultural Sensitivity: Be mindful of cultural differences and ensure that translations are appropriate for the target audience. Avoid idioms or phrases that may not translate well.
• Consistency: Use consistent terminology and style across translations to maintain the integrity of the content. Refer to already translated pages if available.
• Attribution: If you are translating content from another source, provide proper attribution to the original author and source.
• Collaboration: Work with native speakers or professional translators when possible to ensure the highest quality translations. Engage with the community to review and improve translations.
• Tools and Resources: You may use translation tools and resources, but always review and edit machine translations for accuracy.