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.
Thread has gotten pretty long so dont know if this was already mentioned. There are few module docs in Nixpkgs targeting specific modules, often written by maintainers themselves because docstrings aren’t enough.
Can we possibly auto-genrate wiki pages for them and linking back to nixpkgs? So source of truth remains at the source code, but still benefits from SEO and discoverability of wiki.
Unsure on how much effort would be for translation. Might want to limit to unstable/stable branches to reduce page churn. Also want to limit write access to auto generated pages to not lose user changes to wiki on next page gen.
Just something to think about. I don’t know anything about mediawiki, but will happily work on it if people think its a good idea.
(EDIT: sorry, I misread your message and thought you were a maintainer of the old wiki) I definitely don’t want to take any hostile actions against the old wiki (that I both used and tried to improve)… but I still don’t understand why it would be bad to suggest users to check the new wiki with a link like @MikulasVanousek added (maybe with a lack of coordination, possibly explaining why someone removed the links), as it leaves the original content unchanged. The current status (official vs yours that is better referenced by search engines) will inevitably lead to a useless fork of the documentation, which will result in users reading outdated documentation. I guess you can agree, Nix does not need something like that. So, to maintain an healthy spirit, could you please consider adding a link suggesting users to additionally read the official Wiki?
Oh, my bad, I read @JulienMalka 's message to quickly, I thought he was a maintainer of the old wiki, and I thought he reverted the changes of @MikulasVanousek. In my opinion, @MikulasVanousek’s code was the best strategy to solve this issue (and it does not harm the old wiki’s content at all)… but seems like someone reverted this changed, no idea who then…
That’s really sad and, IMHO, quite selfish. Not sure what to do then, except from regularly adding this warning manually, and trying to get the official wiki better referenced.
On a different topic, I see the wiki as a great opportunity to translate the documentation (for now, NixOs’s documentation is very english-orientated). But so far I can’t see a way to add a translation on Wiki’s page. Could the maintainer enable this option?
) power of NixOs). For instance, I once sent a ~3 line PR to simply document the 