Regarding the issue of having two wiki, why can’t we simply add in front of all (or most since the admin will likely not allow us to run a script) pages a warning with a redirection to the new wiki? I just started with the python page:
This should also help with SEO, creating more links to the official wiki page.
For people interested, you can just copy/paste this text and change the URL to provide a proper redirection (or find it later by opening an already modified page like the Python’s one and clicking the source with “Edit”):
{{warning|1=The new official [https://wiki.nixos.org/ NixOs wiki] should now be preferred over this possibly outdated [https://wiki.nixos.org/wiki/FAQ#Why_is_there_a_new_wiki?_What_is_with_nixos.wiki? unofficial] page. We therefore recommend you to check instead https://wiki.nixos.org/wiki/Python.}}
I like this a lot. Hopefully, the old maintainer doesn’t catch up to it. I am looking at the number of pages on the old wiki and it might even be feasible to do this by hand.
I’m strongly against this. Yes, editing the Wiki is more convenient, but all this will lead to is divergence from the source code, and thus, confusion.
Please, everyone, let’s make the Wiki about NixOS for end users. The lack of end-user documentation for NixOS is the primary source of complaints. This is natural: The surface area of NixOS use cases is incredibly large, because of the combinatorics. And popularity of NixOS use cases is driven by trends. This is where a Wiki model will excel. For everything else, we already have ongoing work that just needs more time to bear fruit.
I wrote a script to automate this and now I am trying to add a very similar warning to all the pages. Let’s see if the old wiki maintainer gets rid of my changes.
I don’t understand your point, seems like you are mostly saying that we should not use a wiki at all? (Divergence is unrelated to linking packages to wiki or not, as the user will anyway find the wiki page after googling). If you agree that a wiki is useful, then you should agree that wiki should be for end users, and manual should be for a comprehensive technical documentation, right? Then, users that use search.nixos.org are end users, so they will surely benefit more from reading the wiki than reading the manual (and in any case, we can also link packages to both the wiki and the manual, and add links from wiki to manual as well for greater discoverability).
If you expect the wiki to have poor documentation, then we should just work on it to make it better. Arch linux made a great job at doing that, their wiki is the best source of information I can find on linux in general.
And if multiple workflows are possible, then we should list at least the most common ones, with their pro and cons. To limit divergence from manual to wiki, maybe we should consider moving tutorial-like parts of the manual into the wiki, replacing it with a proper link.
No, I fully support having a Wiki for NixOS use cases. My point is the direction of links: The Wiki should point to “hard” information that is derived from the source, not the other way round.
Yes.
That depends on the concrete use case, and all I suggest is to take care that they are somewhat clearly separated for the different resources, and that the separation is evident for everyone involved.
I don’t have expectations about quality, as you say it’s more or less a function of effort. In the past there was little effort happening around NixOS documentation, and I suspect one reason is that it wasn’t clear where to direct it. This is why I have indeed high hopes for the Wiki, if we set things up the right way.
Absolutely, the reference manuals should be mostly interface listings and examples, with a few introductory words on the mechanisms where needed.
Ok, so seems like we agree on everything, except that manual & source should point to wiki (I do agree, wiki should point to manual).
By “hard” do you mean like “only maintainers can touch”? I still don’t see, in which sense/scenario would this be bad to add this link?
If this is for security/correctness reasons… I don’t think it would change anything, mosts users would still read the wiki anyway (just googling instead of clicking a link) and follow the possibly wrong instructions, irrespective of the existence of this link. Actually, I think adding this link could rather help to maintain a better quality (correct/secure) wiki as it allows people to quickly go to the documentation, and fixing stuff that are unclear.
If this is to avoid frustrating people when providing a bad quality wiki link… bad quality documentation is still better than nothing, and, again, at least it allows people to quickly see which page needs to be fixed to improve the documentation, providing on the long term a better documentation.
If this is by principle, that source should only point to content written by authoritative people… First nothing prevents us from adding a warning with the link like “keep in mind that this content is modified by the community and might not be as technically accurate as the manual”, and also add a link to the manual. Secondly, I still think that users are not stupid, and that providing a practical system is better than providing a theoretically sound system but impractical.
Lastly, i have maybe an idea that could combine best of both worlds: do you think it could make sense to start the important pages of the wiki with a content taken straight from the “tutorial” of the manual, and allow people to freely edit the content after it? This way:
This reduces duplication of information
Important content is still carefully checked by the maintainers
The user can read both the manual and wiki at the same time
The user can still freely edit less sensitive parts of the wiki easily.
By “hard” I mean “mechanically derived from the source”, which is where the only truth is.
I’m primarily concerned with
how information is arranged to be consumed by people effectively
how pieces of information refer to each other
how much effort it is to change or add information
I see a Wiki as a compromise to compensate for the terrible UX of writing code (essentially the whole Unix paradigm of “plain” text and files), but already in principle it can’t be a replacement for branch-and-merge version control and testing. Therefore I’d prefer the Wiki to be auxiliary to everything else. I may be wrong about all this, and maybe things are simpler than I think they are.
you suspected this type of bulk edit would be unwanted by the maintainer, you did it anyway, without contacting him about it, and hoping he doesn’t catch onto it? do i have to explain how bad of a look that is?
Is there maybe a plan to track like improvements/progress to the Wiki configuration (and content) via a separate GitHub Issue project? Or is there an other place where we can structurally coordinate improvements and communicate progress?
Hello, wiki.nixos.org maintainer here,
I would like to ask that everyone refrains from taking hostile actions towards the unofficial wiki. In absolutely no case is it okay to go and pollute the work of the old wiki’s maintainers, we do not want to foster a spirit of conflict in this community.
I am glad to see people being enthusiastic about the official wiki, and I would like to invite everyone to focus their energy into making this new wiki attracting and filled with quality content. If everyone focuses their energy on positive actions towards the new wiki, success will undoubtedly follow.
Still unsure why this is fundamentally an issue to help the user to quickly find the wiki, that is just another official source of information… but anyway.
Sure, git is theoretically great, and fits nicely with content that must be carefully checked like code. But it is, in my experience, way too slow for anything where many minor changes are made like in a documentation (at least given the man (and woman ) power of NixOs). For instance, I once sent a ~3 line PR to simply document the <nixpkgs> syntax nixos/doc: documentation angle bracket syntax by tobiasBora · Pull Request #63033 · NixOS/nixpkgs · GitHub and that was quite a journey. First just to send the changes, you need to understand the heavy xml syntax and compile some stuff (that must be part of the PR, which makes it horrible to review). Then, you need to know git & PR, then you need to wait for review: the first review I got was 4 months later! (Not blaming anyone but the process) And of course, as Nix reviewers care a lot about details (a bit too much I think but it’s another topic), they say “LGTM, but can you change this minor detail”. This adds another round of getting again used to the compilation process (I slept a few night in 4 months… and my focus had changed as well) and waiting for reviews, that will again pin minor details… and it creates so much time, efforts, and frustrations for so few changes… and at the end the PR never got merged as someone else fixed it elsewhere. At least in wiki we don’t have this barrier as anyone can fix the details straight when they see them (often it takes more time to ask someone to apply the fix that fixing it directly), and I think it’s fair to give it a chance
Would it be possible to provide a wiki “function” to provide link to the manual, and possibly an “information” green box with a content like You may also find additional content about XXX in the official manual <link to the good section of the manual> ? I’m afraid that hardcoding the url would break if the manual goes to another page.
Would it be possible to add a category “Language”, as I guess an important fraction of the wiki will describe how to deal with Python/Java/… in Nix, and it is not clear (to me at least) in which category this should go otherwise. It would also help to create a page listing all languages.
) power of NixOs). For instance, I once sent a ~3 line PR to simply document the 