Manual of Style: Difference between revisions

Line 1:

~~<div style="border: 1px solid #D33; background: #FFEBEB; padding: 30px; border-radius: 5px; margin: 10px 0px; display: flex; align-items: center;">~~

~~<div style="color: #D33; font-size: 40px; margin-right: 15px; background: #FFEBEB; display: flex; line-height: 0; align-items: center;">⚠</div>~~

~~<div style="color: #D33; font-size: 15px; font-style: normal; font-weight: 400; line-height: normal; text-align: left;">Under construction!</div>~~

~~</div>~~

Line 77:

Line 72:

=== 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~~.

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.

==== Hierarchy and Structure ====

* Use a clear hierarchy of headings to organize content:

* Level 2 (==) for main sections

* Level 3 (===) for subsections

* Level 4 (====) for sub-subsections

* Avoid going deeper than level 4 unless absolutely necessary

* Begin each article with an introduction (without a heading) that summarizes the topic.

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

1. Introduction (no heading)

2. Installation

3. Configuration

4. Tips and Tricks

5. Troubleshooting

6. References

==== Standard Section Structure ====

* 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.~~

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

* 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~~)

(Introduction)

== Installation ==

~~├── =~~=== Using nix-shell ====

=== Using nix-shell ===

~~├── =~~=== Using Global Configuration ====

=== Using Global Configuration ===

~~└── =~~=== Using Home Configuration ====

=== Using Home Configuration ===

== Configuration ==

~~├── =~~=== Basic ====

=== Basic ===

~~└── =~~=== Advanced ====

=== Advanced ===

== Tips and Tricks ==

~~└── =~~=== Location of Options ====

=== Location of Options ===

== Troubleshooting ==

~~└── =~~=== Issue 1 ====

=== Issue 1 ===

== References ==

</syntaxhighlight>

==== Flexibility ====

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 ===

Line 114:

Line 131:

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.

* 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.

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

== Text formatting ==

Line 164:

Line 181:

** 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

Line 206:

Line 219:

==== Spacing ====

Consistent spacing ~~enhances~~ readability and maintains a clean appearance:

Consistent spacing improves readability and maintains a clean appearance:

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

Line 312:

Line 325:

== Vocabulary ==

Consistent use of terminology is crucial for maintaining clarity across the NixOS Wiki. This section outlines key terms and their preferred usage:

* Nix: The package manager and build system at the core of NixOS.

* NixOS: The Linux distribution built on top of the Nix package manager.

* Nixpkgs: The collection of packages available for Nix and NixOS.

* Derivation: A description of how to build a package in Nix.

* Expression: A piece of Nix code that describes how to build something.

* Channel: A versioned set of Nix expressions and binaries.

* Flake: A newer way to package Nix code with explicit dependencies and outputs.

* Attribute: A named value in a Nix expression, often used to refer to packages or configuration options.

* Configuration.nix: The main configuration file for a NixOS system.

When using these terms:

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

* Provide brief explanations for technical terms when they're first introduced in an article.

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

== Linking ==

Proper linking improves navigation and provides additional context for readers. This section covers different types of links used in the NixOS Wiki.

==== Wikilinks ====

Wikilinks are internal links to other pages within the NixOS Wiki.

* 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>

* For section links, use a hash symbol: <syntaxhighlight lang="mediawiki">[[Page Name#Section Name]]</syntaxhighlight>

==== External linking ====

External links point to resources outside the NixOS Wiki.

* Use single square brackets for external links: <syntaxhighlight lang="mediawiki">[https://example.com Link text]</syntaxhighlight>

* If no link text is provided, the URL itself will be displayed: <syntaxhighlight lang="mediawiki">[https://example.com]</syntaxhighlight>

* For bare URLs, no brackets are needed: <syntaxhighlight lang="mediawiki">https://example.com</syntaxhighlight>

==== Category links ====

~~== Disambiguation~~ pages ==

Category links help organize pages into groups.

* Add category links at the bottom of the page: <syntaxhighlight lang="mediawiki">[[Category:Category Name]]</syntaxhighlight>

* Multiple categories can be added to a single page.

* To link to a category page without adding the current page to that category, use a colon before "Category": <syntaxhighlight lang="mediawiki">[[:Category:Category Name]]</syntaxhighlight>

== Images ==

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

Images can greatly improve 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.

Line 350:

Line 401:

* user-home-directory-structure.jpg

== ~~Copyrighted material~~ ==

== Videos ==

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

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

* ~~'''Permission~~:'~~'' Always obtain permission before using copyrighted material~~.

* Relevance: Only include videos that directly support the article's content.

* ~~'''Fair use~~:~~''' If claiming fair use~~, ~~clearly state this and provide a rationale~~.

* Hosting: Use reputable video hosting platforms (e.g., YouTube, Vimeo) to embed videos.

* ~~'''Attribution~~:~~''' Properly attribute all copyrighted material~~ to ~~its source~~.

* Permissions: Ensure you have the right to use and embed the video content.

* ~~'''Licenses~~:~~''' Use~~ content ~~with compatible licenses (e.g., Creative Commons)~~.

* Accessibility: Provide a text description or transcript of the video content for users who cannot view or hear the video.

* ~~'''Public domain~~:~~''' Clearly mark content that is in~~ the ~~public domain.~~

* Embedding: Use the appropriate wiki syntax to embed videos:

~~To attribute copyrighted material:~~

{{~~Attribution~~

| ~~author = Original Author~~

~~| source = https://example.com/original-source~~

| ~~license = CC BY-SA 4.0~~

}}

</syntaxhighlight>

<~~div style="border~~: ~~1px solid #2E8B57; background: #DFF2DF; padding: 30px; border-radius: 5px; margin: 10px 0px; display: flex; align-items: center;"~~>

Replace VIDEO_ID with the actual YouTube video ID, and PARAMETERS with any additional settings.

<~~div style="color: #2E8B57; font-size: 40px; margin-right: 15px; background: #DFF2DF; display: flex; line-height: 0; align-items~~: ~~center;">✦~~</~~div~~>

<~~div style="color~~: ~~#2E8B57; font-size: 15px; font-style: normal; font-weight: 400; line-height: normal;~~ text-~~align: left;">This template does not yet exist! Remove this note if added~~.~~</div>~~

* Size: Set an appropriate size for embedded videos, typically no wider than 640 pixels.

~~</div>~~

* Captions: Include a descriptive caption below the video.

* Alternative: Always provide a text-based alternative or summary of the video content within the article.

== Lists ==

Lists help organize information in a clear, readable format. The NixOS Wiki uses two types of lists:

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

=== Unordered lists ===

=~~= Videos ==~~

Use asterisks (*) for bullet points. Indent with additional asterisks for nested lists.

* First item

* Second item

** Subitem 1

** Subitem 2

* Third item

</syntaxhighlight>

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

=== Ordered lists ===

...

Use hash symbols (#) for numbered lists. Indent with additional hash symbols for nested lists.

# First step

# Second step

## Substep 1

## Substep 2

# Third step

</syntaxhighlight>

== ~~Wiki markup styling~~ ==

=== List guidelines ===

~~== Lists ==~~

* Use sentence case for list items.

* Be consistent with punctuation (either use periods at the end of all items or none).

* Keep list items parallel in structure.

* Avoid mixing ordered and unordered lists unless necessary for clarity.

== Tables ==

Tables are useful for presenting structured data. Here's how to create and format tables in the NixOS Wiki:

=== Basic table structure ===

Use the following syntax to create a basic table:

{| class="wikitable" style="text-align: center; width: 500px;"

|-

! Header 1 !! Header 2 !! Header 3

|-

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

|-

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

|}

</syntaxhighlight>

=== Table formatting ===

* Use <code>class="wikitable"</code> for consistent styling.

* Start each row with <code>|-</code>

* Use <code>!</code> for header cells and <code>|</code> for regular cells.

* Align cell content using <code>style="text-align: left/center/right;"</code>

=== Table guidelines ===

* Keep tables simple and easy to read.

* Use headers to clearly describe the content of each column.

* Avoid excessive use of tables when prose or lists would suffice.

* For complex tables, consider using additional CSS classes or inline styles for better formatting.

== 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~~.

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.

* 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~~.

=== General Principles ===

* ~~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~~.

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

* ~~Tools~~ and ~~Resources~~: ~~You may use translation tools and resources~~, but ~~always~~ review and ~~edit machine~~ translations for ~~accuracy~~.

* Clarity: Prioritize clear, understandable language over literal translations.

* Consistency: Maintain consistent terminology and style across all translated pages.

* Cultural Sensitivity: Be mindful of cultural differences and adapt content appropriately.

=== Translation Process ===

==== Preparation ====

* Familiarize: Read the entire original article to understand context and technical terms.

* Research: Identify established translations for NixOS-specific terms in your target language.

* Tools: Machine translation is allowed for a general foundation, but it must be reviewed.

==== Translation ====

* Translate Content: Begin with the main body of the article.

* Maintain Structure: Preserve the original article's structure and formatting.

* Technical Terms: Use glossaries for consistent translation of technical terms.

* Proper Nouns: Generally, do not translate names of tools, projects, or people.

==== Review and Refinement ====

* Self-Review: Proofread your translation for accuracy and fluency.

* Peer Review: If possible, have a native speaker review the translation.

* Technical Review: Ensure technical accuracy, especially for code snippets and commands.

=== Language-Specific Guidelines ===

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

* Address unique challenges or conventions for each language.

* Provide guidance on translating or adapting idiomatic expressions.

=== Handling Untranslatable Content ===

* Code Snippets: Generally, do not translate code. Provide translated comments if necessary.

* Commands: Keep command syntax unchanged, but translate descriptions and explanations.

=== Metadata and Navigation ===

* Page Titles: Use translated titles, but include the original title in parentheses.

* Categories: Create and use translated category names.

* Interlanguage Links: Add appropriate interlanguage links to connect corresponding articles across languages.

=== Quality Assurance ===

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

* Encourage feedback from readers and act on suggestions for improvement.

* Conduct periodic audits of translated content to maintain overall quality and consistency.

== Templates ==

Templates are pre-formatted pieces of content that can be reused across multiple pages. They help maintain consistency and reduce repetitive work.

=== Common templates ===

* Warning: A warning box used to report potential danger.

* Note: A note box used to emphasize important information.

* Tip: A tip box used to share helpful hints.

* Expansion: An expansion flag used to indicate incomplete articles.

=== Using templates ===

To use a template, enclose its name in double curly braces:

</syntaxhighlight>

For templates with parameters:

</syntaxhighlight>

==== Template markup ====

~~== Documentation ==~~

When creating new templates:

* Use clear, descriptive names for templates.

* Document the purpose and usage of the template on its talk page.

* Use <noinclude> tags for content that should only appear on the template page itself.

== References ==

Proper referencing is crucial for maintaining the credibility and verifiability of wiki content. Follow these guidelines for references:

=== Citation styles ===

* Use inline citations with numbered references:

This is a statement that needs a reference.<ref>Author Name, "Article Title", Publication, Date. URL</ref>

</syntaxhighlight>

* For multiple uses of the same reference, use named references:

First use of the reference.<ref name="example">Author Name, "Article Title", Publication, Date. URL</ref>

...

Later use of the same reference.<ref name="example" />

</syntaxhighlight>

=== General guidelines ===

* Prefer primary sources and official documentation when available.

* Avoid referencing personal blogs or unreliable sources.

* For software-specific information, link to the official documentation or repository.

* When referencing specific versions of software, include the version number in the citation.

[[Category:Contributions]]

@@ Line 1: / Line 1: @@
-<div style="border: 1px solid #D33; background: #FFEBEB; padding: 30px; border-radius: 5px; margin: 10px 0px; display: flex; align-items: center;">
-    <div style="color: #D33; font-size: 40px; margin-right: 15px; background: #FFEBEB; display: flex; line-height: 0;  align-items: center;">⚠</div>
-    <div style="color: #D33; font-size: 15px; font-style: normal; font-weight: 400; line-height: normal; text-align: left;">Under construction!</div>
-</div>
 <div style="border: 1px solid #2E8B57; background: #DFF2DF; padding: 30px; border-radius: 5px; margin: 10px 0px; display: flex; align-items: center;">
      <div style="color: #2E8B57; font-size: 40px; margin-right: 15px; background: #DFF2DF; display: flex; line-height: 0; align-items: center;">✦</div>
@@ Line 77: / Line 72: @@
 === 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.
+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.
+==== Hierarchy and Structure ====
+* Use a clear hierarchy of headings to organize content:
+  * Level 2 (==) for main sections
+  * Level 3 (===) for subsections
+  * Level 4 (====) for sub-subsections
+  * Avoid going deeper than level 4 unless absolutely necessary
+* Begin each article with an introduction (without a heading) that summarizes the topic.
+* Arrange sections in a logical order, typically following this pattern:
+. Introduction (no heading)
+. Installation
+. Configuration
+. Tips and Tricks
+. Troubleshooting
+. References
+==== Standard Section Structure ====
-* <strong>Hierarchy:</strong> 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.
+For consistency across the wiki, use the following structure where applicable:
-* <strong>Flow:</strong> Arrange sections in a logical order, starting with an introduction and moving through the main points before concluding.
-<strong>e.g.</strong> Where applicable, you must use the following structure:
 <syntaxhighlight lang="text">
-(Description)
+(Introduction)
 == Installation ==
-├── ==== Using nix-shell ====
+=== Using nix-shell ===
-├── ==== Using Global Configuration ====
+=== Using Global Configuration ===
-└── ==== Using Home Configuration ====
+=== Using Home Configuration ===
 == Configuration ==
-├── ==== Basic ====
+=== Basic ===
-└── ==== Advanced ====
+=== Advanced ===
 == Tips and Tricks ==
-└── ==== Location of Options ====
+=== Location of Options ===
 == Troubleshooting ==
-└── ==== Issue 1 ====
+=== Issue 1 ===
 == References ==
 </syntaxhighlight>
+==== Flexibility ====
+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 ===
@@ Line 114: / Line 131: @@
 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.
+* <strong>Limit Characters:</strong> 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.
+* <strong>Conciseness:</strong> Strive for brevity without sacrificing clarity. Consider rephrasing complex ideas or breaking them down into multiple sections.
 == Text formatting ==
@@ Line 164: / Line 181: @@
 ** Main sections (==): Use title case
 ** Subsections (===, ====): Use sentence case
-** Example:
-*** Installation Process
-*** Preparing the installation media
 * <strong>Proper nouns:</strong> Always capitalize names of specific people, places, organizations, and NixOS-specific components.
 ** Example: Nix, NixOS, Nixpkgs, Eelco Dolstra
@@ Line 206: / Line 219: @@
 ==== Spacing ====
-Consistent spacing enhances readability and maintains a clean appearance:
+Consistent spacing improves readability and maintains a clean appearance:
 * <strong>Single space after periods:</strong> Use only one space after a period at the end of a sentence.
@@ Line 312: / Line 325: @@
 == Vocabulary ==
+Consistent use of terminology is crucial for maintaining clarity across the NixOS Wiki. This section outlines key terms and their preferred usage:
+* <strong>Nix:</strong> The package manager and build system at the core of NixOS.
+* <strong>NixOS:</strong> The Linux distribution built on top of the Nix package manager.
+* <strong>Nixpkgs:</strong> The collection of packages available for Nix and NixOS.
+* <strong>Derivation:</strong> A description of how to build a package in Nix.
+* <strong>Expression:</strong> A piece of Nix code that describes how to build something.
+* <strong>Channel:</strong> A versioned set of Nix expressions and binaries.
+* <strong>Flake:</strong> A newer way to package Nix code with explicit dependencies and outputs.
+* <strong>Attribute:</strong> A named value in a Nix expression, often used to refer to packages or configuration options.
+* <strong>Configuration.nix:</strong> The main configuration file for a NixOS system.
+When using these terms:
+* Be consistent in capitalization (e.g., always "NixOS", never "Nixos" or "NIXOS").
+* Provide brief explanations for technical terms when they're first introduced in an article.
+* Use the full term on first mention, followed by any abbreviation in parentheses if it will be used later.
 == Linking ==
+Proper linking improves navigation and provides additional context for readers. This section covers different types of links used in the NixOS Wiki.
 ==== Wikilinks ====
+Wikilinks are internal links to other pages within the NixOS Wiki.
+* 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>
+* For section links, use a hash symbol: <syntaxhighlight lang="mediawiki">[[Page Name#Section Name]]</syntaxhighlight>
 ==== External linking ====
+External links point to resources outside the NixOS Wiki.
+* Use single square brackets for external links: <syntaxhighlight lang="mediawiki">[https://example.com Link text]</syntaxhighlight>
+* If no link text is provided, the URL itself will be displayed: <syntaxhighlight lang="mediawiki">[https://example.com]</syntaxhighlight>
+* For bare URLs, no brackets are needed: <syntaxhighlight lang="mediawiki">https://example.com</syntaxhighlight>
 ==== Category links ====
-== Disambiguation pages ==
+Category links help organize pages into groups.
+* Add category links at the bottom of the page: <syntaxhighlight lang="mediawiki">[[Category:Category Name]]</syntaxhighlight>
+* Multiple categories can be added to a single page.
+* To link to a category page without adding the current page to that category, use a colon before "Category": <syntaxhighlight lang="mediawiki">[[:Category:Category Name]]</syntaxhighlight>
 == Images ==
-Images can greatly enhance the content of wiki articles. When using images, follow these guidelines:
+Images can greatly improve 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.
@@ Line 350: / Line 401: @@
 * user-home-directory-structure.jpg
-== Copyrighted material ==
+== Videos ==
-Respecting copyright is crucial. Follow these guidelines when dealing with copyrighted content:
+Videos can be a valuable addition to wiki articles, especially for tutorials or demonstrations. Follow these guidelines:
-* '''Permission:''' Always obtain permission before using copyrighted material.
+* <strong>Relevance:</strong> Only include videos that directly support the article's content.
-* '''Fair use:''' If claiming fair use, clearly state this and provide a rationale.
+* <strong>Hosting:</strong> Use reputable video hosting platforms (e.g., YouTube, Vimeo) to embed videos.
-* '''Attribution:''' Properly attribute all copyrighted material to its source.
+* <strong>Permissions:</strong> Ensure you have the right to use and embed the video content.
-* '''Licenses:''' Use content with compatible licenses (e.g., Creative Commons).
+* <strong>Accessibility:</strong> Provide a text description or transcript of the video content for users who cannot view or hear the video.
-* '''Public domain:''' Clearly mark content that is in the public domain.
+* <strong>Embedding:</strong> Use the appropriate wiki syntax to embed videos:
-To attribute copyrighted material:
 <syntaxhighlight lang="mediawiki">
-{{Attribution
+{{#ev:youtube|VIDEO_ID|PARAMETERS}}
- | author = Original Author
- | source = https://example.com/original-source
- | license = CC BY-SA 4.0
-}}
 </syntaxhighlight>
-<div style="border: 1px solid #2E8B57; background: #DFF2DF; padding: 30px; border-radius: 5px; margin: 10px 0px; display: flex; align-items: center;">
+Replace VIDEO_ID with the actual YouTube video ID, and PARAMETERS with any additional settings.
-    <div style="color: #2E8B57; font-size: 40px; margin-right: 15px; background: #DFF2DF; display: flex; line-height: 0; align-items: center;">✦</div>
-    <div style="color: #2E8B57; font-size: 15px; font-style: normal; font-weight: 400; line-height: normal; text-align: left;">This template does not yet exist! Remove this note if added.</div>
+* <strong>Size:</strong> Set an appropriate size for embedded videos, typically no wider than 640 pixels.
-</div>
+* <strong>Captions:</strong> Include a descriptive caption below the video.
+* <strong>Alternative:</strong> Always provide a text-based alternative or summary of the video content within the article.
+== Lists ==
+Lists help organize information in a clear, readable format. The NixOS Wiki uses two types of lists:
-'''Note:''' When in doubt about the copyright status of material, do not use it. It's better to err on the side of caution.
+=== Unordered lists ===
-== Videos ==
+Use asterisks (*) for bullet points. Indent with additional asterisks for nested lists.
+<syntaxhighlight lang="mediawiki">
+* First item
+* Second item
+** Subitem 1
+** Subitem 2
+* Third item
+</syntaxhighlight>
-Videos can be a valuable addition to wiki articles, especially for tutorials or demonstrations. Follow these guidelines:
+=== Ordered lists ===
-...
+Use hash symbols (#) for numbered lists. Indent with additional hash symbols for nested lists.
+<syntaxhighlight lang="mediawiki">
+# First step
+# Second step
+## Substep 1
+## Substep 2
+# Third step
+</syntaxhighlight>
-== Wiki markup styling ==
+=== List guidelines ===
-== Lists ==
+* Use sentence case for list items.
+* Be consistent with punctuation (either use periods at the end of all items or none).
+* Keep list items parallel in structure.
+* Avoid mixing ordered and unordered lists unless necessary for clarity.
 == Tables ==
+Tables are useful for presenting structured data. Here's how to create and format tables in the NixOS Wiki:
+=== Basic table structure ===
+Use the following syntax to create a basic table:
+<syntaxhighlight lang="mediawiki">
+{| class="wikitable" style="text-align: center; width: 500px;"
+|-
+! Header 1 !! Header 2 !! Header 3
+|-
+| Row 1, Cell 1 || Row 1, Cell 2 || Row 1, Cell 3
+|-
+| Row 2, Cell 1 || Row 2, Cell 2 || Row 2, Cell 3
+|}
+</syntaxhighlight>
+=== Table formatting ===
+* Use <code>class="wikitable"</code> for consistent styling.
+* Start each row with <code>|-</code>
+* Use <code>!</code> for header cells and <code>|</code> for regular cells.
+* Align cell content using <code>style="text-align: left/center/right;"</code>
+=== Table guidelines ===
+* Keep tables simple and easy to read.
+* Use headers to clearly describe the content of each column.
+* Avoid excessive use of tables when prose or lists would suffice.
+* For complex tables, consider using additional CSS classes or inline styles for better formatting.
 == 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.
-* <strong>Accuracy:</strong> Translations should be accurate and faithful to the original content. Avoid adding or omitting information that could alter the meaning.
+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>Cultural Sensitivity:</strong> Be mindful of cultural differences and ensure that translations are appropriate for the target audience. Avoid idioms or phrases that may not translate well.
-* <strong>Consistency:</strong> Use consistent terminology and style across translations to maintain the integrity of the content. Refer to already translated pages if available.
+=== General Principles ===
-* <strong>Attribution:</strong> If you are translating content from another source, provide proper attribution to the original author and source.
-* <strong>Collaboration:</strong> Work with native speakers or professional translators when possible to ensure the highest quality translations. Engage with the community to review and improve translations.
+* <strong>Accuracy:</strong> Strive for translations that faithfully represent the original content without altering meaning or omitting information.
-* <strong>Tools and Resources:</strong> You may use translation tools and resources, but always review and edit machine translations for accuracy.
+* <strong>Clarity:</strong> Prioritize clear, understandable language over literal translations.
+* <strong>Consistency:</strong> Maintain consistent terminology and style across all translated pages.
+* <strong>Cultural Sensitivity:</strong> Be mindful of cultural differences and adapt content appropriately.
+=== Translation Process ===
+==== Preparation ====
+* <strong>Familiarize:</strong> Read the entire original article to understand context and technical terms.
+* <strong>Research:</strong> Identify established translations for NixOS-specific terms in your target language.
+* <strong>Tools:</strong> Machine translation is allowed for a general foundation, but it must be reviewed.
+==== Translation ====
+* <strong>Translate Content:</strong> Begin with the main body of the article.
+* <strong>Maintain Structure:</strong> Preserve the original article's structure and formatting.
+* <strong>Technical Terms:</strong> Use glossaries for consistent translation of technical terms.
+* <strong>Proper Nouns:</strong> Generally, do not translate names of tools, projects, or people.
+==== Review and Refinement ====
+* <strong>Self-Review:</strong> Proofread your translation for accuracy and fluency.
+* <strong>Peer Review:</strong> If possible, have a native speaker review the translation.
+* <strong>Technical Review:</strong> Ensure technical accuracy, especially for code snippets and commands.
+=== Language-Specific Guidelines ===
+* Maintain a separate page for language-specific translation guidelines.
+* Address unique challenges or conventions for each language.
+* Provide guidance on translating or adapting idiomatic expressions.
+=== Handling Untranslatable Content ===
+* <strong>Code Snippets:</strong> Generally, do not translate code. Provide translated comments if necessary.
+* <strong>Commands:</strong> Keep command syntax unchanged, but translate descriptions and explanations.
+=== Metadata and Navigation ===
+* <strong>Page Titles:</strong> Use translated titles, but include the original title in parentheses.
+* <strong>Categories:</strong> Create and use translated category names.
+* <strong>Interlanguage Links:</strong> Add appropriate interlanguage links to connect corresponding articles across languages.
+=== Quality Assurance ===
+* Regularly review and update translations to ensure they remain accurate and up-to-date.
+* Encourage feedback from readers and act on suggestions for improvement.
+* Conduct periodic audits of translated content to maintain overall quality and consistency.
 == Templates ==
+Templates are pre-formatted pieces of content that can be reused across multiple pages. They help maintain consistency and reduce repetitive work.
+=== Common templates ===
+* <strong>Warning:</strong> A warning box used to report potential danger.
+* <strong>Note:</strong> A note box used to emphasize important information.
+* <strong>Tip:</strong> A tip box used to share helpful hints.
+* <strong>Expansion:</strong> An expansion flag used to indicate incomplete articles.
+=== Using templates ===
+To use a template, enclose its name in double curly braces:
+<syntaxhighlight lang="mediawiki">
+{{TemplateName}}
+</syntaxhighlight>
+For templates with parameters:
+<syntaxhighlight lang="mediawiki">
+{{TemplateName|parameter1=value1|parameter2=value2}}
+</syntaxhighlight>
 ==== Template markup ====
-== Documentation ==
+When creating new templates:
+* Use clear, descriptive names for templates.
+* Document the purpose and usage of the template on its talk page.
+* Use <strong><noinclude></strong> tags for content that should only appear on the template page itself.
 == References ==
+Proper referencing is crucial for maintaining the credibility and verifiability of wiki content. Follow these guidelines for references:
+=== Citation styles ===
+* Use inline citations with numbered references:
+<syntaxhighlight lang="mediawiki">
+This is a statement that needs a reference.<ref>Author Name, "Article Title", Publication, Date. URL</ref>
+</syntaxhighlight>
+* For multiple uses of the same reference, use named references:
+<syntaxhighlight lang="mediawiki">
+First use of the reference.<ref name="example">Author Name, "Article Title", Publication, Date. URL</ref>
+...
+Later use of the same reference.<ref name="example" />
+</syntaxhighlight>
+=== General guidelines ===
+* Prefer primary sources and official documentation when available.
+* Avoid referencing personal blogs or unreliable sources.
+* For software-specific information, link to the official documentation or repository.
+* When referencing specific versions of software, include the version number in the citation.
 [[Category:Contributions]]