Manual of Style: Difference between revisions
Agreed changes from https://github.com/NixOS/nixos-wiki-infra/issues/98 - part 1 of X |
2 / X (title case to sentence case) |
||
| Line 68: | Line 68: | ||
=== Article titles === | === 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 | 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 sentence case with capitalizing only the first letter of the first word. | ||
* <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. | ||
| Line 88: | Line 88: | ||
* Arrange sections in a logical order, typically following this pattern: | * Arrange sections in a logical order, typically following this pattern: | ||
1. Introduction (no heading) | 1. Introduction (the introduction has no heading) | ||
2. Installation | 2. Installation | ||
3. Configuration | 3. Configuration | ||
4. Tips and | 4. Tips and tricks | ||
5. Troubleshooting | 5. Troubleshooting | ||
6. References | 6. References | ||
| Line 104: | Line 104: | ||
== Installation == | == Installation == | ||
==== Using nix-shell ==== | ==== Using nix-shell ==== | ||
==== Using | ==== Using global configuration ==== | ||
==== Using | ==== Using home configuration ==== | ||
== Configuration == | == Configuration == | ||
| Line 111: | Line 111: | ||
==== Advanced ==== | ==== Advanced ==== | ||
== Tips and | == Tips and tricks == | ||
==== Location of | ==== Location of options ==== | ||
== Troubleshooting == | == Troubleshooting == | ||
| Line 146: | Line 146: | ||
* <strong>Articles, blog posts, and short stories:</strong> Use double quotation marks | * <strong>Articles, blog posts, and short stories:</strong> Use double quotation marks | ||
** Example: "Understanding Nix Flakes", "The NixOS | ** Example: "Understanding Nix Flakes", "The NixOS installation guide" | ||
* <strong>Software names, tools, and commands:</strong> Use regular text, typically with initial capitalization | * <strong>Software names, tools, and commands:</strong> Use regular text, typically with initial capitalization | ||
| Line 161: | Line 161: | ||
* <strong>Short quotes (less than 40 words):</strong> Use double quotation marks ("") and incorporate into the text. | * <strong>Short quotes (less than 40 words):</strong> 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 | ** Example: According to the documentation, "NixOS is a Linux distribution built on top of the Nix Package Manager." | ||
* <strong>Long quotes (40 words or more):</strong> Use block quotes by indenting the entire quote or using the <strong>blockquote</strong> tag. | * <strong>Long quotes (40 words or more):</strong> Use block quotes by indenting the entire quote or using the <strong>blockquote</strong> tag. | ||
| Line 178: | Line 178: | ||
Proper capitalization improves readability and maintains a professional appearance: | Proper capitalization improves readability and maintains a professional appearance: | ||
* <strong>Article titles:</strong> Use | * <strong>Article titles:</strong> Use sentence case, capitalizing only the first word. | ||
** Example: Installing NixOS on a | ** Example: Installing NixOS on a virtual machine | ||
* <strong>Section headers:</strong> | * <strong>Section headers:</strong> | ||
** Main sections (==): Use | ** Main sections (==): Use sentence case | ||
** Subsections (===, ====): Use sentence case | ** Subsections (===, ====): Use sentence case | ||
* <strong>Proper nouns:</strong> Always capitalize names of specific people, places, organizations, and NixOS-specific components. | * <strong>Proper nouns:</strong> Always capitalize names of specific people, places, organizations, and NixOS-specific components. | ||
| Line 188: | Line 188: | ||
* <strong>Common nouns:</strong> Do not capitalize unless they are part of an official name or at the beginning of a sentence. | * <strong>Common nouns:</strong> Do not capitalize unless they are part of an official name or at the beginning of a sentence. | ||
** Example: " | ** Example: "Every distribution has a package manager." but "Nix Package Manager" | ||
* <strong>Acronyms and initialisms:</strong> Generally use all caps, but follow official styling if different. | * <strong>Acronyms and initialisms:</strong> Generally use all caps, but follow official styling if different. | ||