Manual of Style: Difference between revisions
2 / X (title case to sentence case) |
mNo edit summary |
||
| (6 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Notice | |||
|icon=✦ | |||
|color=var(--border-color-success) | |||
|background=var(--background-color-success-subtle) | |||
|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. | |||
}} | |||
<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. | <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. | ||
| Line 12: | Line 14: | ||
Any new content incorporated into this page must directly address a persistently recurring style issue. | Any new content incorporated into this page must directly address a persistently recurring style issue. | ||
== Rules of | == Rules of thumb == | ||
* <strong>Use | * <strong>Use common sense:</strong> Always apply logic and reason when contributing to the wiki. | ||
* <strong>Cite | * <strong>Cite reliable sources:</strong> Aim to ensure that all information added is verifiable and comes from reliable sources. | ||
* <strong>Maintain | * <strong>Maintain neutrality:</strong> Strive to present information in a neutral and unbiased manner. | ||
* <strong>Be | * <strong>Be clear and concise:</strong> Use clear, concise, and grammatically correct language to ensure readability and understanding. | ||
* <strong>Follow | * <strong>Follow site guidelines:</strong> Adhere to the site's guidelines and policies at all times. | ||
* <strong>Avoid | * <strong>Avoid edit wars:</strong> Engage in constructive discussions to resolve content disputes rather than engaging in edit wars. | ||
* <strong>Protect | * <strong>Protect privacy:</strong> Do not share personal information about yourself or others without consent. | ||
* <strong>Contribute | * <strong>Contribute constructively:</strong> Aim to improve the quality of the content and the overall user experience. | ||
* <strong>Use | * <strong>Use proper formatting:</strong> Follow the wiki's formatting guidelines to ensure consistency and readability. | ||
* <strong>Stay | * <strong>Stay on topic:</strong> Ensure that contributions are relevant to the subject matter of the page. | ||
* <strong>Report | * <strong>Report issues:</strong> Report any issues or inappropriate behavior to the administrators promptly. | ||
* <strong>Be | * <strong>Be patient and helpful:</strong> Assist new users and be patient with those who are still learning the ropes. | ||
* <strong>Respect | * <strong>Respect others:</strong> Treat all users with respect and courtesy. Personal attacks and harassment are strictly prohibited. | ||
* <strong>No | * <strong>No advertising, vandalism, or spamming:</strong> Contributions should be constructive and relevant. Any form of advertising, vandalism, or spamming will not be tolerated. | ||
* '''Stay on | * '''Stay on topic:''' This wiki is only about NixOS, Nixpkgs, Nix and the Nix-ecosystem. | ||
== Content | == Content policy == | ||
=== Plagiarizing === | === Plagiarizing === | ||
| Line 43: | Line 45: | ||
Vandalism refers to any act of deliberately adding false or misleading information, deleting content, or otherwise compromising the integrity of the wiki. | Vandalism refers to any act of deliberately adding false or misleading information, deleting content, or otherwise compromising the integrity of the wiki. | ||
* <strong>Types of | * <strong>Types of vandalism:</strong> This includes adding false information, deleting pages, inserting inappropriate content, and spamming links. | ||
* <strong>Response:</strong> Vandalized pages will be promptly reverted to their previous state. Persistent vandals will be blocked from editing. | * <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. | * <strong>Reporting:</strong> Users are encouraged to report vandalism immediately. | ||
=== Spam and | === Spam and advertisement === | ||
Spamming and advertising are prohibited to keep the wiki free from clutter and irrelevant content. | Spamming and advertising are prohibited to keep the wiki free from clutter and irrelevant content. | ||
| Line 55: | Line 57: | ||
* <strong>Action:</strong> Spammers will have their content removed and may be banned from editing. Legitimate contributions should not include promotional content. | * <strong>Action:</strong> Spammers will have their content removed and may be banned from editing. Legitimate contributions should not include promotional content. | ||
=== Unofficial | === Unofficial wikis === | ||
Hostility towards other wikis is not tolerated. Editors who make hostile comments about other wikis will be warned and may be blocked. | Hostility towards other wikis is not tolerated. Editors who make hostile comments about other wikis will be warned and may be blocked. | ||
* <strong>Linking to | * <strong>Linking to other wikis:</strong> Linking to other wikis is not prohibited if such links contribute to the quality of the content. | ||
* <strong>Contribution | * <strong>Contribution recommendation:</strong> 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, headings, and sections == | ||
| Line 71: | Line 73: | ||
* <strong>Consistency:</strong> Ensure that article titles are consistent with the titles of related content to maintain a cohesive structure across the wiki. | * <strong>Consistency:</strong> Ensure that article titles are consistent with the titles of related content to maintain a cohesive structure across the wiki. | ||
* <strong>Avoid | * <strong>Avoid redundancy:</strong> Do not include unnecessary words or phrases that do not add value to the title. | ||
=== Section | === Section organization === | ||
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. | 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 | ==== Hierarchy and structure ==== | ||
* Use a clear hierarchy of headings to organize content: | * Use a clear hierarchy of headings to organize content: | ||
| Line 93: | Line 95: | ||
4. Tips and tricks | 4. Tips and tricks | ||
5. Troubleshooting | 5. Troubleshooting | ||
6. References | 6. See also | ||
7. References | |||
==== Standard | ==== Standard section structure (applications) ==== | ||
For consistency across the wiki, use the following structure where applicable: | For consistency across the wiki, use the following structure where applicable: | ||
| Line 103: | Line 106: | ||
== Installation == | == Installation == | ||
==== | ==== Shell ==== | ||
==== | ==== System setup ==== | ||
== Configuration == | == Configuration == | ||
| Line 112: | Line 114: | ||
== Tips and tricks == | == Tips and tricks == | ||
== Troubleshooting == | == Troubleshooting == | ||
== | |||
== See also == | |||
== References == | == References == | ||
| Line 124: | Line 126: | ||
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. | 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 | === 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. | 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. | ||
| Line 131: | Line 133: | ||
* <strong>Consistency:</strong> Maintain consistency in the formatting and style of section headers throughout the article. | * <strong>Consistency:</strong> Maintain consistency in the formatting and style of section headers throughout the article. | ||
=== Length | === Length restrictions === | ||
Be mindful of length restrictions when crafting titles and section headings. Excessively long names can make navigation difficult and negatively impact readability. | Be mindful of length restrictions when crafting titles and section headings. Excessively long names can make navigation difficult and negatively impact readability. | ||
* <strong>Limit | * <strong>Limit characters:</strong> Section headings should ideally remain under 40 characters. | ||
* <strong>Conciseness:</strong> 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. | ||
| Line 245: | Line 247: | ||
** Use numerals for 10 and above. | ** Use numerals for 10 and above. | ||
** Use commas for numbers with four or more digits (e.g., 1,000, 10,000). | ** Use commas for numbers with four or more digits (e.g., 1,000, 10,000). | ||
** Use dots as decimal separator (e.g. 1,000.23 ) | |||
** For very large numbers, consider using words (e.g., 1 million instead of 1,000,000). | ** For very large numbers, consider using words (e.g., 1 million instead of 1,000,000). | ||
| Line 257: | Line 260: | ||
** Include the time zone when relevant (e.g., 14:30 UTC). | ** Include the time zone when relevant (e.g., 14:30 UTC). | ||
* <strong> | * <strong>Software versions:</strong> | ||
** | ** Software versions are subject to change. Only add software versions when required by the content. | ||
==== Abbreviations ==== | ==== Abbreviations ==== | ||
| Line 343: | Line 346: | ||
When using these terms: | When using these terms: | ||
* Be consistent in capitalization (e.g., always "NixOS", never "Nixos" or "NIXOS"). | * 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 the full term on first mention, followed by any abbreviation in parentheses if it will be used later. | ||
| Line 356: | Line 358: | ||
* Use double square brackets to create a wikilink: <syntaxhighlight lang="mediawiki">[[Page Name]]</syntaxhighlight> | * 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> | * 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> | * For section links, use a hash symbol. Please note: Section headings are sometimes changed during editing - it may be overlooked to change all the necessary references to them as well. Section links should therefore be used sparingly: <syntaxhighlight lang="mediawiki">[[Page Name#Section Name]]</syntaxhighlight> | ||
==== External linking ==== | ==== External linking ==== | ||
| Line 393: | Line 395: | ||
Proper image file naming helps with organization and searchability: | Proper image file naming helps with organization and searchability: | ||
* '''Descriptive names:''' Use clear, descriptive file names (e.g., " | * '''Descriptive names:''' Use clear, descriptive file names (e.g., "nixos-installation-partitioning.png"). | ||
* '''Lowercase:''' Use lowercase letters to avoid case-sensitivity issues. | * '''Lowercase:''' Use lowercase letters to avoid case-sensitivity issues. | ||
* '''Hyphens:''' Use hyphens (-) to separate words, not underscores or spaces. | * '''Hyphens:''' Use hyphens (-) to separate words, not underscores or spaces. | ||
| Line 464: | Line 466: | ||
| Row 2, Cell 1 || Row 2, Cell 2 || Row 2, Cell 3 | | Row 2, Cell 1 || Row 2, Cell 2 || Row 2, Cell 3 | ||
|} | |} | ||
</syntaxhighlight>Writers who use the GUI editor must then add (using the „Edit source“ mode):<syntaxhighlight lang="mediawiki"> | |||
style="text-align: center; width: 500px;" | |||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 484: | Line 488: | ||
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. | 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. | ||
=== General | === General principles === | ||
* <strong>Accuracy:</strong> Strive for translations that faithfully represent the original content without altering meaning or omitting information. | * <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>Clarity:</strong> Prioritize clear, understandable language over literal translations. | ||
* <strong>Consistency:</strong> Maintain consistent terminology and style across all translated pages. | * <strong>Consistency:</strong> Maintain consistent terminology and style across all translated pages. | ||
* <strong>Cultural | * <strong>Cultural sensitivity:</strong> Be mindful of cultural differences and adapt content appropriately. | ||
=== Translation | === Translation process === | ||
==== Preparation ==== | ==== Preparation ==== | ||
| Line 501: | Line 505: | ||
==== Translation ==== | ==== Translation ==== | ||
* <strong>Translate | * <strong>Translate content:</strong> Begin with the main body of the article. | ||
* <strong>Maintain | * <strong>Maintain structure:</strong> Preserve the original article's structure and formatting. | ||
* <strong>Technical | * <strong>Technical terms:</strong> Use glossaries for consistent translation of technical terms. | ||
* <strong>Proper | * <strong>Proper nouns:</strong> Generally, do not translate names of tools, projects, or people. | ||
==== Review and | ==== Review and refinement ==== | ||
* <strong>Self- | * <strong>Self-review:</strong> Proofread your translation for accuracy and fluency. | ||
* <strong>Peer | * <strong>Peer review:</strong> If possible, have a native speaker review the translation. | ||
* <strong>Technical | * <strong>Technical review:</strong> Ensure technical accuracy, especially for code snippets and commands. | ||
=== Language- | === Language-specific guidelines === | ||
* Maintain a separate page for language-specific translation guidelines. | * Maintain a separate page for language-specific translation guidelines. | ||
| Line 518: | Line 522: | ||
* Provide guidance on translating or adapting idiomatic expressions. | * Provide guidance on translating or adapting idiomatic expressions. | ||
=== Handling | === Handling untranslatable content === | ||
* <strong>Code | * <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. | * <strong>Commands:</strong> Keep command syntax unchanged, but translate descriptions and explanations. | ||
=== Metadata and | === Metadata and navigation === | ||
* <strong>Page | * <strong>Page titles:</strong> Use translated titles, but include the original title in parentheses. | ||
* <strong>Categories:</strong> Create and use translated category names. | * <strong>Categories:</strong> Create and use translated category names. | ||
* <strong>Interlanguage | * <strong>Interlanguage links:</strong> Add appropriate interlanguage links to connect corresponding articles across languages. | ||
=== Quality | === Quality assurance === | ||
* Regularly review and update translations to ensure they remain accurate and up-to-date. | * Regularly review and update translations to ensure they remain accurate and up-to-date. | ||
| Line 537: | Line 541: | ||
== Templates == | == Templates == | ||
Templates are pre-formatted pieces of content that can be reused across multiple pages. They help maintain consistency and reduce repetitive work. | Templates are pre-formatted pieces of content that can be reused across multiple pages. They help maintain consistency and reduce repetitive work. For a detailed list of templates, see [[Help:Template]]. | ||
=== Common templates === | === Common templates === | ||