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:
Installation
Configuration
Tips and Tricks
Troubleshooting
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.
I was trying to send an email to the admins at [email protected] but the email was not deliverable.
This is the email address shown on the main page:
This is the mail system at host mout-p-102.mailbox.org.
I'm sorry to have to inform you that your message could not
be delivered to one or more recipients. It's attached below.
For further assistance, please send mail to postmaster.
If you do so, please include this problem report. You can
delete your own text from the attached returned message.
The mail system
<[[email protected]](mailto:[email protected])>: host mx2.improvmx.com[2a05:d012:412:e202:e81e:cc44:3b53:8a3d]
said: 550 5.1.1 The email account that you tried to reach does not exist.
Please try double-checking the recipient's email address for typos or
unnecessary spaces. - ImprovMX (in reply to RCPT TO command)
As per the NixOS wiki contribution guidelines, language on the wiki has to be simple and concise. As of writing this, the flake article is the exact opposite of that. I'm not the most knowledgeable on flakes, but if anyone here is, I think this is an important thing to do given how widely used flakes are.
The following screenshot shows, that the search is normally hidden on mobile. No search bar or button is shown in the default view, or by scrolling down.
The search however becomes visible, if the user scrolls sideways. This is very unintuitive for a mobile use case.
For better UX, the search bar or a search button should be visible without horizontal scrolling.
I think it would be very neat to have the ability to declare a given article is about a specific package (or packages) in Nixpkgs. This would improve clarity of the wiki article, and it would facilitate integration with search.nixos.org. Besides Source and Homepage, there could be a link to an article about a package, if there is one on the wiki. This would make it much easier to learn the differences between versions of packages. For example, for the Julia language has the following versions of packages:
julia
julia-bin
julia-lts
julia_18
julia_18-bin
All these point to the same home page. You might think the difference between all these packages is immediately obvious from the names, but there is a more detailed description on the wiki. It would be neat to immediately see that a wiki article exists about these packages.
Approach
There are two fundamental approaches: marking the relationship in meta attribute of each package (like homepage) or marking it in the wiki.
The easier way to implement this feature would be to add a meta attribute to the packages. Then, displaying it in the search results would be as easy as displaying the other links in meta. But I think this approach has some disadvantages. Nixpkgs is already responsible for a lot. Changing the wiki links will would be slow, especially for people on stable. Changing the wiki is much simpler than merging a pull request to Nixpkgs. Furthermore, you would likely mention the relationship on the wiki too, which means you repeat yourself and split the source of truth.
If the relationship is marked in the wiki (with some kind of a tag), you would then query the wiki for all articles related to each packages. After getting the response of the search from the backed, the extract the package_attr_name and query the wiki for articles about the packages you are displaying. It would be trivial if you wanted to query the packages one by one, but I would have to make more research into how exactly we could get the wiki links for all the packages with one request..
I do not know much about SEO, but this seems possibly due to wiki.nixos.org lacking a robots.txt. It might be prudent to copy https://nixos.wiki/robots.txt directly.
Should we format the nix code on the wiki with the nixfmt-rfc-style formatter?
This would make it so that the code on the wiki is following the same style that currently in the process of being adopted by nixpkgs.
Automating this could bring some issues with it, some of these being the unintended formatting of code that is intended to be formatted differently than the standard defined in RFC166, another one is that it could turn into a fight against the tools when editing.
We would need to find out how we investigate how the tools will behave when run against the wiki!
The commons is an archive of lots of images, that we could reuse, instead of uploading our own. Mediawiki can automatically fetch and proxy file references that already exist in commons.
This plugin makes the whole workflow faster and should be preferred over the built-in $wgUseInstantCommons
The Gentoo Wiki uses a specially designed template to allow translating section names while still keeping HTML anchors with the source language name intact. This allows using links of the form https://wiki.nixos.org/wiki/Hydra#Installation in all languages regardless of the actual translation of Installation. The template is described here. Additionally the Gentoo Wiki also implements a special template for linking to translated pages here. This template allows redirecting users to the source language version of a page whenever a translated version does not exist.
Looking at Special:ListGroupRights, I see a number of groups, some of which appear to be in active use. Where can documentation for them be found? Are there material criteria for these roles?
Nix vim is a nice to configure vim it is based on NeoVim but the only documentation is here it allows you to configure vim using nix. So whats so special about?? It special since you don't need to have a separate config for vim in Lua rather you can just use nix. You can use Lua for plugins but It set your vim up for Nix/NixOS. Since the wiki just came out it would be cool to include something that use nix.
A multilingual wiki can make NixOS more international, but it may also require more complex maintenance and moderation. So I'm not sure whether it is a good idea to make the site multilingual, it is just a suggestion.
The MediaWiki language extension bundle (MLEB) is a curated set of MediaWiki extensions offering multilingual features. It attempts to provide an easy way to bring comprehensive language support to a MediaWiki.
The current version of MLEB contains the following extensions: [1]
MLEB has a quarterly release schedule, so that you can easily stay on the cutting edge with the constantly improving language support. The bundle is tested against recent MediaWiki release versions, so you can avoid most of the temporary breaks that would happen if you were using the latest development versions of each extension.
I think that it is known at this point that NixOS now has an official wiki. But the old wiki (https://nixos.wiki) should be removed or have the domain redirect to https://wiki.nixos.org.
Someone brought up on the Brazilian NixOS community that there isn't much Nix-related content in Brazilian Portuguese (PT-BR). I wonder if the community could start working on this by translating/contributing to the wiki in Brazilian Portuguese.