Contribution Page: "Manual of Style"

[Layer-09]

In my recent efforts to contribute to the NixOS official wiki, I have identified a critical need for standardization across the platform. The current state of the wiki is characterized by a lack of uniformity, with no two pages displaying consistent structure or format. This disorganization significantly undermines the efficacy and accessibility of the wiki as a resource. Consequently, I propose a plan for the systematic uniformization of the NixOS wiki.

Important

This is a foundational framework, not an exhaustive guide. Feedback and suggestions are encouraged.

Initiative 1: Standardized Page Categorization

To establish a coherent structure, it is imperative that we adopt a uniform naming convention for the page categories. I propose the following standardized categories, to be implemented in this specific order across all wiki pages:

1. Installation
2. Configuration
3. Tips and Tricks
4. Troubleshooting
5. References

Currently, similar categories appear sporadically under varied names and orders (e.g., "Install" instead of "Installation"). Implementing consistent naming and ordering will significantly enhance user experience by providing a predictable and navigable structure.

Initiative 2: Uniform Content Guidelines

Beyond standardizing category names, we must establish specific content guidelines for each category to ensure comprehensive and consistent information. For instance:

• Description: A detailed description of the software/service, preferably 100-150 words.
• Installation:
  • Using nix-shell
  • System-Wide Installation on NixOS
  • User-Specific Installation with Home Manager
• Configuration:
  • Basic
  • Advanced
• Tips and Tricks
• Troubleshooting
• References: Allow users to trace the sources of information that contributed to the creation of the page.

Initiative 3: Pre-formatted Code with Alejandra

To ensure the highest quality of code formatting, we should use Alejandra, the only formatter right now that does not compromise on quality. All code examples should be pre-formatted using Alejandra to ensure consistency and readability, at least until nixfmt-rfc-style resolves its current issues and becomes the official formatter. (#57)

Initiative 4: Enhanced Tagging System

The current tagging system, inherited from the old wiki, merely clutters the user experience with pages that are hardly navigable. An updated tagging system is essential. I propose the following structured approach:

• Major Category → Category → Subcategory → Pages

For example, the "Applications" or "Gaming" tags offer minimal utility. Instead, adopting a more structured approach, with the "Software" tag as the major one would greatly improve the navigation:

• Software
  • Server
    • Mailserver
      • Maddy
      • Mailman
  • Desktop
    • Communications
      • Signald
      • Discord

A more intuitive structure would replace Hardware → Hardware → Framework Laptop 13 with Hardware → Laptops → Framework Laptop 13.

Initiative 5: Regular Audits and Updates

To maintain the relevance and accuracy of the wiki, regular audits and updates are essential. This involves:

• Automated Monitoring Tools: Implement tools to flag outdated content or broken links, prompting reviews and updates.
• Editorial Board: Form an editorial board comprising experienced NixOS users and developers to oversee the quality and consistency of updates.
• Community Engagement: Promote the wiki across various NixOS communities (Discord, Reddit, Discourse, Stack Overflow, IRC, Matrix, Telegram, etc.) to ensure it is recognized as the central place of our collective knowledge. Pinning it would be the best case scenario.

Note

I urge the community to support and contribute to this initiative, as a unified approach will benefit all users. By embracing these initiatives, we can transform the NixOS wiki into a structured, user-friendly, and reliable tool for the NixOS community.

[Mic92]

This issue looks like it was created by chatgpt or a similar tool. I would prefer your original thoughts over chatgpt as it just bloats up text with nothing-ness. Let's start again.

[Layer-09]

I am surprised by the blatant attempt to downplay my initiative. I have carefully condensed information and used academic English to minimize ambiguity for the reader.

I have addressed this matter with reference to various reputable Linux wikis, including Arch and Gentoo. I have thoroughly reviewed all pages on the current NixOS wikis to understand the existing contribution system and have familiarized myself with their tagging system. I have also briefed myself with GitHub formatting rules and reviewed all issues, both open and closed, in this repository.

NixOS is an amazing piece of technology, but it is currently plagued by poor documentation and a lack of clear direction. Beginners frequently post about their struggles with this os, because of that. It is our responsibility to pave a way for them, and the official wiki is the solution to all this.

Any response to this request other than proceeding with it would be inappropriate and disregarding to its preparation. I respectfully request that my contribution be given due consideration.

[Mic92]

Sorry if my previous message was not clear. Can you open a new issue but not use some AI to generate the text. Also since you brought up several topics, it would make sense to split them up into differen issues as it's otherwise hard to discuss them.

[Mic92]

Initiative 3: Pre-formatted Code with Alejandra

The same question we have for nixfmt-rfc-style also apply to Alejandra, so it's not in a better position and we should use nixfmt where possible as this is what the whole NixOS community now standardizes on. However a problem I see with automatically applying everywhere is that we sometimes just publish incomplete nix code i.e. omitting {} - this is sometimes more readable, but it will break these formatters expecting correct syntax.

[Layer-09]

That’s why I emphasized pre-formatting using {}. This can be done on the contributor's computer or through the online tool at https://kamadorueda.com/alejandra/, provided it fits within the website's character limits. While I can't speak to the efficacy of nixfmt, I can personally vouch for Alejandra. I use it daily to format my code, and it consistently delivers readable, accessible, and error-free results. I'm even prepared to handle the formatting on the wiki myself if we decide to proceed with this approach.

Naturally, we will omit the {} on the wiki for improved readability. The extra indents can be safely removed with https://onlinetexttools.com/unindent-text.

[Profpatsch]

@Layer-09 how come this issue is your only contribution on github?

[Layer-09]

@Layer-09 how come this issue is your only contribution on github?

I created this account specifically to host my NixOS dotfiles on GitHub and contribute to the NixOS community. Initially, I hosted my dotfiles here, but I had to include some large assets in the dotfiles folder because I wipe my partitions between boots.

This forced me to use Git LFS. However, after encountering several issues, I decided to stop hosting my dotfiles on GitHub and deleted the repository altogether. Since then, I've used this account solely for code references.

I've followed the NixOS official wiki since it went live, but only recently decided to contribute directly. This led to the creation of this issue.

[klinger]

I start with Initiative 4: Enhanced Tagging System
Tagging is the wrong word in mediawiki terminology. Lets talk about „Categories“: The OP framework example is a bit missleading, because we currently have two ordering systems: By category and in a few cases by sub-page. I am almost done in categorizing all pages not organized in sub-pages. These sub-pages have to be handled carefully and with respect to former wiki editors, thats why its still there.

Almost all pages are are available by three clicks from the start page. The major categories are: Software, Hardware, Desktop, Server, Community.

The click paths are:
Main Page --> page (for NixOS beginners in „Getting Started“ and Wiki contributors)
Main Page --> Big 5 Categories --> page
Main Page --> Big 5 Categories --> Sub Category --> page

The Main Page is mostly for users who dont know, what they want. Most experienced users just use the search or come to a page via search engine. Thats why it is so important to have some „easy“ articles in the beginning and a not so difficult click path.

We have to discuss with the mostly hardware related sub-page structure. Its possible to argue it has not to be touched because its so special, that experienced users will find it by search.

I think, we may further adjust the categories - but there is no need for a big change here. Its more important to enhance and in some cases rewrite the articles for NixOS beginners. The Getting-Started part is still a bit too complicated.

(I fully support other parts of OP initiative, but I will write this in another comments)

[klinger]

Initiative 1: Standardized Page Categorization and Initiative 2: Uniform Content Guidelines
Lets rephrase this to „standardized page templates“ and „guide to fill in a template“. I have extensive work experience in doing this for applications. I think it is a good idea.

In the current state of this wiki it may be good to have a nice looking but not too complicated page template for applications. The most basic way to do this my be the easiest for the wiki editors:

• a page like application_template, that can be copy-pasted in new articles
• a page like application_template_guide with lots of information how to fill in the template (e.g. for description NOT 150 words, but only a link to the official webpage of the product and a short 1 to 4 sentence description to faster understand the page in NixOS wiki)
• a link to this templates in Category:Applications
• a perfectly filled in article about one application (this should also be linked from the category as perfect example)

I am not sure whether it makes sense to encode template version numbers in it - because the content will never be good enough to automatically be extracted in NixOS manual, thats why it is not so important to make it completely consistant. I would try to tag the version number, so it would be possible to update the application articles.

In summary I think we can benefit from making, discussing and using this template. A small BUT though: A lot of the energy of the central NixOS documentation people just goes into making the processes for documentation - often with quite high effort to code changesand such stuff. For the wiki we can benefit from this, but the main problem is not the missing template. Its the missing content.

Three examples:
We may have documentation for some mail servers - but there is no documentation about mailclients. We have only some desktop environments documented and only in a quite basic way.
There are quite a few examples for ActivityPub server systems - but there a lot of interesting web based applications missing.

Aside from this template idea there is also need for unifying the wiki editing guidelines and articles about it. They are a bit distributed and could be merged or restructured. Not my main interest though, I will focus on content for the NixOS beginners. Somebody can just pick this up and do it.

[Layer-09]

I appreciate your points, and I'd like to address both of them.

First, consider how we currently access the MPV page I recently created, which falls under the "Applications" category. We navigate through Software → Applications → (Ctrl+F) MPV. While this only takes three clicks from the start page, it isn't the most intuitive process.

Imagine a library named "Software" with a single bookshelf labeled "Applications." Initially, this seems fine, but soon you realize every type of book is crammed onto this one shelf with minimal organization. This setup isn't sustainable and certainly isn't user-friendly.

I commend your recent addition of the "Media Player" subcategory—it's a step in the right direction. However, the current structure still falls short. A more logical and accessible path would be Software → Desktop → Media Player → MPV. This might require an extra click, but the improved clarity and organization would be well worth it.

Moreover, broad and ambiguous categories like "Applications" or "Gaming" offer little value and can be confusing, especially when "Applications" is used both as a topic and a subcategory.

While experienced users might rely on the search bar, I enjoy exploring categories to discover what else is compatible with NixOS. Therefore, a more intuitive and organized categorization would greatly improve this experience.

Lastly, I have no concerns with the getting started section.

---

Now, regarding the second part: I wholeheartedly agree that a pre-made template is an excellent idea. There's no need to worry about missing content initially; no wiki entry is ever complete from the start. It's a community-driven platform, and contributors will naturally fill in the gaps over time, especially as the wiki gains popularity.

However, I recommend against placing it in the "Applications" topic/subcategory for the reasons I previously mentioned. Instead, it would be much more effective to transform the "Contribute" page into a new category called "Contributions." This new category could serve as a comprehensive hub for everything related to contributing, making it easier for both new and experienced contributors to find the resources they need.

[klinger]

I agree, that the structure is not the most logical. There are also the problem of a page called „Applicactions“ that shows the Nix-Ecosystem Applications. But the name is too long for the side navigation.

Lets look at Category:Gaming. I would like to have sub categories like „Launcher“, „Retrogaming“, „(Voice-)Chat“, „Wine/Proton“ and for every genre of games. But we currently only have 19 pages there. There is no need for sub categories now (sub categories would make the situation worse - it would hide content instead making it better discoverable).

Lets look at the Category:Applications. Yes. Its enough articles now to make sub categories. But we still need this cateory to have a category for all articles, that should use the application-template - but thats more for maintainance. Its not needed for the users to navigate to the page - there could be other ways. But there is still content missing: My „Media Player“ Category makes no sense until we have the SMPlayer and VLC articles.

Instead of moving around the navigation now I would focus on three things:

1. Write more articles
2. Lets create an application/software template and get consensus on it
3. Lets apply it to the existing 180 articles (that will take quite a long time)

We can categorize them with sub categories of the category Applications (there are only two yet: Audio and Media Player) while doing the third step.

In this way the Category:Applications will naturally become a link list to the sub categories, and the sheer amount of pages below does not matter that much.

--
Software -> Desktop -> Media Player approach:
I can understand it from the perspective of a software centric wiki. But the NixOS wiki is about the operating system, and users here need more information concerning desktops (drivers, hardware, installation images, etc.). If we rename it to Desktop-Software it could work though.

[Layer-09]

Alright, you made some excellent points. I agree that it would be wise to postpone my fourth initiative for now, at least until we've addressed the other priorities.

However, I strongly believe we should move forward with replacing "Contribute" with a "Contributions" category. This change will centralize all necessary resources, making it easier for contributors to find what they need.

[klinger]

Then how about: You start with the Category:Contributing

There are NixOS Wiki:Contributing and https://wiki.nixos.org/wiki/Contributing and some other snippets to contributing in the wiki (Community section, Workgroups). You can reorder/restructure it. Keep in mind while editing to only doing your nice enhancement rewrites of the English texts. And not to change the meaning of the texts or expanding it (too much). This category would be a good place to work on the template.

My guess: Only very few of the wiki contributers have read this part of the wiki. The logical place for the template in a perfect world is here. But for casual contributors I think it is necessary to mix the user documentation about software with the wiki-editor documentation about templates. But there is no harm to just link it from there.

There will be some changes on the front page you couldnt do: I ll do it or get somebody to get it done (deleting redirects and pages, edit the side navigation). You can start with creating the category and moving content. The empty Wiki:Contriibution page could just have the manual link „see Category:Contributing”, and we will tidy up later.

[Layer-09]

If anyone wants to review https://wiki.nixos.org/wiki/Contributing, please go ahead. If possible, change its name to "NixOS Contributor's Guide". I tried that myself, but I get some template errors.

I'll leave "Contributing to Nix" and "Contributing to the documentation" to anyone interested. In the coming days, I'll add the remaining pages to further detail the syntax and the default template.

[tomodachi94]

If anyone wants to review https://wiki.nixos.org/wiki/Contributing, please go ahead.

We should definitely move the section about contributing to the wiki itself to https://wiki.nixos.org/wiki/NixOS_Wiki:Contributing (note that the project namespace is in the title).

[Layer-09]

I'm encountering some challenges with the editing template and lack the necessary experience with MediaWiki source formatting to resolve them on my own. I would greatly appreciate it if the "Configuration" code snippets could remain unchanged while allowing contributors to edit them from the graphical panel.

Below, you'll find the usage instructions for the template. I believe this template eliminates the need for separate pages on syntax and style.

{{Editing Template
|package_name= your_package_name
|configuration=<!-- Configuration content goes here -->
|tips_and_tricks=<!-- Tips and Tricks content goes here -->
|troubleshooting=<!-- Troubleshooting content goes here -->
|references=<!-- References content goes here -->
}}

[tomodachi94]

I can definitely take a look (I have a few years of experience with wikitext), but I don't think a template is the best way to go here.

Instead, I think we should build a manual of style. Wikipedia's is a good but extremely lengthy example. The FTB Wiki's MOS¹ is also a good one that is related to technical writing.

Footnotes

1. COI declaration: I'm an administrator there. ↩

[Layer-09]

Over the past two weeks, I have gained more experience with the wiki and have now started working on the official Manual of Style. If there is anyone interested, please consider contributing to it. It is important to have as many contributors as possible working on it to create a collectively appreciated manual.

This issue has become quite broad in nature, and some might argue that it was from the start (which I acknowledge). Therefore, I will consider this issue resolved once we have fully introduced the manual. To better reflect this, I will also update the title of this issue.

Additionally, while working on the overall documentation for the manual (and reading #48), I believe we should establish projects for both future/wanted articles and translation. I'm not sure if the moderators have given further thought to multilingual support since their last message, so I'll add this to stimulate discussion.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/nixos-wiki-now-with-translations/48653/3

[Layer-09]

I've completed the MoS and would greatly appreciate it if someone could review it. Thank you!

[Mic92]

I just read through the style guide and agree with the content. I think we only need to do changes when we switch to the link template: #119

[Mic92]

Approved.

[klinger]

Manual of Style

Summer 2024

I really like the MoS. I have some remarks to a small part of this text.

Rules of Thumb

Cite Reliable Sources:

I dont think it is necessary and possible to cite all information. This isnt a wikipedia with relevance-criteria and a need to be perfectly correct and citated in all cases. Maybe we should write this a bit softer like „try to to add verifiable sources...“?

With this strict rule, most content would have to be deleted. This should be a goal and a part of a good article, but not the requirement to participate.

Stay on Topic (NEW)

I would add a paragraph like: „The NixOS wiki is about NixOS and Nix and the Nix-ecosystem. Stay on topic and do not use it for other topics."

Content Policy

Plagiarizing

I agree with this, but it may be a bit overkill in cases like citing one sentence from wikipedia or an applications home page. It may work this way though if we dont enforce it in these cases.
Maybe add to prevention: „Dont even just copy and paste a single sentence - at least change it a bit".

Article titles, headings and sections

Standard Section Structure

This applies mostly to applications - shouldnt it be reflected in the name of the heading like: Standard Section Structure (Applications)

Text Formatting

Capital letters

Article titles

I am strong opponent to capitalization of all major words. I would prefer just the first word and proper nouns/official names capitalized. (Maybe we can discuss and vote on this in a wiki meeting). For me it is uncommon to see these words with a capital letter at the beginning, it disrupts the reading flow and makes it impossible to see, whether it is an official name or just MoS capital letter.

Numbers and dates

Numbers

There is a convention for the decimal separator missing.

I am living in the half of the word where we write 1.000,23 and not 1,000.23 - but we just have to decide what to do here (a good use for needing a MoS).

Versions

Rename paragraph to "Software versions"
I would rephrase the text a bit softer in a way like this: "Software versions are prone to change. Add software versions only when it is necessary for the content."

Vocabulary

"Provide brief explanations for technical terms when they're first introduced in an article." should be removed. It is not necessary to explain these 9 terms (Nix) in every article. In articles for beginners, it may be necessary to link to a an explanation article.

Linking

Wikilinks

There should be a sentence for sections links to encourage not to use these links too much - they are prone to change (and may not be spotted as easily as changed page names)

Images

Image file names

The descriptive name example and the lowercase rule contradict each other. Better make the example lowercase.

Tables

People use the WYSIWYG editor to create tables. Here should be a paragraph explaining what to to after creating a table with it.