search

NixOS / foundation

This is the home of the NixOS Foundation
61 stars 16 forks source link

Official NixOS Wiki #113

Closed Lassulus closed 2 months ago

Lassulus commented 5 months ago

https://nixos.wiki was created a long time ago and has been useful to the community. We would now like to make the content of this wiki official.

Motivation

The current wiki has a few issues:

All of this creates some uncertainty and leads to some people not contributing to the wiki.

The goal is to create a long term solution with open and transparent participation.

Proposed implementation

We propose to create a new team that would be responsible for the wiki.

The software will still be MediaWiki, so we can retain compatibility with the old wiki. We already have the software, system configuration and backups available to port the data over.

We propose folding the wiki with the documentation team under wiki.nixos.org. This would also make migrating content between the wiki and the documentation more natural.

We have a team of 4 people motivated to do server administration (@Mic92, @RaitoBezarius, @lassulus, @JulienMalka). The documentation is on board, the infra team is on board.

Team Responsibilities

The wiki team will be responsible for maintaining and monitoring the content of the wiki, as well as the system configuration.

Rollout

We propose to launch the wiki under wiki.nixos.org, and wait a few months before declaring it "official". The URL would be fixed so we don't have to migrate the content (and break references).

We merge changes from the old wiki, and point people to the new one. Ideally, automated. Ideally with the help of the old wiki maintainers.

What have we already done

We prepared a NixOS wiki configuration that can import the current wiki content. It provides Authentication through email or Github Login. In the process we improved the upstream mediawiki module in nixpkgs.

nixos-discourse commented 5 months ago

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

https://discourse.nixos.org/t/official-nixos-wiki/38715/1

infinisil commented 5 months ago

Great initiative!

Regarding the domain, https://github.com/nix-rfc-canonical-domain/rfcs is an RFC draft to unify nix.dev and nixos.org into a single canonical domain, currently proposing to move everything to nix.dev, but I think a two-step process would be better:

But considering that, I think it would be better for the wiki to use wiki.nixos.org, such that we limit the domain spread.

Lassulus commented 5 months ago

But if the proposal is to move everything to nix.dev shouldn't we move the wiki also there? moving a domain later is very bad for a wiki SEO wise, which is also a concern we have with the old wiki.

infinisil commented 5 months ago

@Lassulus Yeah I don't think everything should be moved to nix.dev anymore, at least initially. Having a canonical domain, whatever it may be, is a first goal, and we're almost there with only nix.dev being out of line. I'll probably change the RFC draft there to just propose moving nix.dev to docs.nixos.org. In fact, we probably don't even need an RFC for this, we should be able to do that with consensus in the docs team.

deviantsemicolon commented 5 months ago

Great initiative!

Regarding the domain, https://github.com/nix-rfc-canonical-domain/rfcs is an RFC draft to unify nix.dev and nixos.org into a single canonical domain, currently proposing to move everything to nix.dev, but I think a two-step process would be better:

* Move nix.dev under nixos.org as `docs.nixos.org`, which establishes the canonical domain goal with minimal changes

* Optionally in another step, the entirety of `nixos.org` could be moved to `nix.dev` (or another domain), but that's a much larger hammer and not really necessary

But considering that, I think it would be better for the wiki to use wiki.nixos.org, such that we limit the domain spread.

Would nixos.org become a redirect to nix.dev so outdated links don't break?

mightyiam commented 5 months ago

Feedback. I don't like the referring to Nix as NixOS such as in nixos.org domain.

infinisil commented 5 months ago

@deviantsemicolon @mightyiam For such feedback to the RFC draft, please instead give it in https://github.com/nix-rfc-canonical-domain/rfcs by opening an issue or a PR (in the spirit of https://github.com/NixOS/rfcs/pull/138).

Melkor333 commented 5 months ago

Thanks a lot for this proposal! It's about time :)

Are there any plans to improve content quality aswell? E.g. is the plan that the documentation team would be focussing on improving these docs? Or complex new nix features require an entry in the wiki to be merged?

I also remember some discussions on "content ownership". Like some wiki pages are "owned" & maintained by e.g. the maintainers of related packages... (Given this is all on a voluntary basis I'm not sure that would help much, though)

fricklerhandwerk commented 5 months ago

This is a great initiative, thanks a lot @Mic92 and @Lassulus! From the development perspective I strongly support having a Wiki about NixOS, because it lowers the threshold to contributions where they lack most.

As proposed in the Wiki development Matrix room, and similar to what I wrote elswhere:

  1. Please put the wiki under nixos.org.

    It's mainly about NixOS already, and this is where the coverage and quality of documentation is currently worst.

  2. Make it absolutely clear that the Wiki is about NixOS and state its exact purpose.

    Everything else sort of works - independently of NixOS - with reference documentation (Nixpkgs and Nix manuals) and a bit of guidance (nix.dev). A Wiki won't help in those places, and will be counter-productive to the currently ongoing homogenisaiton and centralisation.

  3. Let's resolve the broader domain issue independently.

    There seems to be no clear consensus yet over the target audience (developers vs many more are quite representative), and no consensus on whether to have "one big product" or rather an ecosystem of many independent but related components, or a strategy for how to make any option actually work well - currently it feels like we're in an uncanny valley in between. We cannot, and therefore should not attempt to, solve that right here where it's essentially about re-establishing an existing resource.

is the plan that the documentation team would be focussing on improving these docs?

@Melkor333

It would be great to have people focus on NixOS documentation generally. I hope that the Wiki will make that easier and more likely to happen. The current documentation team doesn't have much capacity for that. Our current strategy is to make improvements from the bottom up, starting at the Nix manual, which implies that NixOS will come last.

Of course anyone is invited to just go ahead and do things they find important! As a team we will help guide users and contributors to the right people and places. We will definitely advertise the official Wiki as a source for NixOS information, which is a lot easier if it has a clearly defined purpose.

MatthewCroughan commented 5 months ago

One thing that has prevented me from contributing to nixos.wiki in the past is attribution. It's not clear who contributed the content. The knowledge is given for free, just as code is. But we should be able to see who wrote it, and a clear edit history like Wikipedia, or git commits. I think this would increase content quality because people would be likely feel more responsible for the content they produce, and be proud of the contributions due to the attribution, as is also true of pull requests and merge reviews.

Edit: It looks like the edit history is available, but hidden unless you log in, as the theme is hiding it unless you're considered an 'editor'. You can log in with GitHub now too. Still, attribution feels hidden, I would like to see a theme that puts the attribution and edit history front and center.

100% would like to see an official wiki and look forward to contributing.

Pablo1107 commented 5 months ago 
1. **Please put the wiki under nixos.org.**
   It's mainly about NixOS already, and this is where the coverage and quality of documentation is currently worst.

2. **Make it absolutely clear that the Wiki is about NixOS** and state its exact purpose.
   Everything else sort of works - independently of NixOS - with reference documentation (Nixpkgs and Nix manuals) and a bit of guidance (nix.dev). A Wiki won't help in those places, and will be counter-productive to the currently ongoing homogenisaiton and centralisation.

I think there is a place for non-NixOS use cases in the wiki. There are a lot of Nix users (like myself) that uses Home Manager, Nix Darwin and other community projects that helps using Nix on several devices. It would be nice to have all the content for how to use Nix for some of these alternative use cases covered.

Just to name an example, say you have an article about some GUI application and how to install it and use it in NixOS, but have a note in the article stating that for non-NixOS users you would need to wrap the application with NixGL which is a common problem someone would face trying to install a GUI application and have a link to the NixGL article stating the different ways to use it.

Mic92 commented 5 months ago

I guess we go for wiki.nixos.org than, I wasn't in sync what the plans with nix.dev were.

infinisil commented 5 months ago

2. Make it absolutely clear that the Wiki is about NixOS and state its exact purpose. Everything else sort of works - independently of NixOS - with reference documentation (Nixpkgs and Nix manuals) and a bit of guidance (nix.dev). A Wiki won't help in those places, and will be counter-productive to the currently ongoing homogenisaiton and centralisation.

I don't think it's reasonable or realistic to try to enforce it being only for NixOS. People will write entries for whatever they think is worth writing down. We absolutely do still need properly reviewed documentation, but not everybody can spend weeks on PR back-and-forths.

So the choice is not between reviewed documentation and unreviewed wiki entries, but rather it's between lower-quality wiki entries and it not being written down at all, or somewhere else (such as the old wiki).

We should think of the wiki as a breeding ground for documentation. It can give us a good sense of what needs to be documented, striving to not need the wiki at all.

The current documentation team doesn't have much capacity for that. Our current strategy is to make improvements from the bottom up, starting at the Nix manual, which implies that NixOS will come last.

To clear this up: You're focusing on that, but everybody else from the docs team is doing different things :)

Majiir commented 5 months ago

Just as the Arch wiki is useful for users configuring software on other distros, so too can the NixOS wiki. NixOS is simply the project where users are likely to be using Nix and Home Manager and NixOS services and...

So, being not a foundation member or docs team member but a user, nixpkgs contributor, and very-small-time nixos.wiki contributor, I think wiki.nixos.org is a natural home for all things Nix.

Looking forward to seeing wiki improvements in any case!

nstgc commented 5 months ago

Just as the Arch wiki is useful for users configuring software on other distros, so too can the NixOS wiki.

I don't think that's a fair comparison. By design, Arch Linux is as generic as reasonably possible while NixOS goes in the opposite direction.

RaitoBezarius commented 5 months ago

Just as the Arch wiki is useful for users configuring software on other distros, so too can the NixOS wiki.

I don't think that's a fair comparison. By design, Arch Linux is as generic as reasonably possible while NixOS goes in the opposite direction.

I think we were talking about the context of Nix-derivative distributions, not any distribution. So I think that's a fair comparison.

zimbatm commented 5 months ago

Added this to the foundation agenda for discussion next Tuesday. We'll give you an update them.

infinisil commented 5 months ago

Added this to the foundation agenda for discussion next Tuesday. We'll give you an update them.

I actually don't think the foundation needs to or even should be involved in deciding over this, because this is strictly a non-administrative topic.

If there was any sort of controversy around doing this I'd propose an RFC, but at least from the reactions to this issue, that doesn't appear to be the case, so there's no need to have an RFC.

So really I think the next step here is doing this! :rocket:

thufschmitt commented 5 months ago

I actually don't think the foundation needs to or even should be involved in deciding over this, because this is strictly a non-administrative topic.

It should not, but the board is currently the only instance with the ability to make a decision on such a thing if they get blocked by any reason, which is why this was escalated there (anyone, correct me if I'm truncating the history).

At any rate, we should give this a few more days to give everyone a chance to voice their opinion.

infinisil commented 5 months ago

It should not, but the board is currently the only instance with the ability to make a decision on such a thing

This directly contradicts this sentence on the foundation board page (Edit: Actually not directly, but you get it..)

The board is not responsible for technical leadership, decisions, or direction.

And it's not just in writing, I also remember hearing the foundation board mention this. If even at all, this should be a last resort option.

if they get blocked by any reason, which is why this was escalated there

I cannot remember or find any instance of this being blocked in any way before. If that actually exists, please link to it or give more context.

So to me it looks like it's absolutely not the foundation's decision.

RaitoBezarius commented 5 months ago

It should not, but the board is currently the only instance with the ability to make a decision on such a thing

This directly contradicts this sentence on the foundation board page:

The board is not responsible for technical leadership, decisions, or direction.

And it's not just in writing, I also remember hearing the foundation board mention this. If even at all, this should be a last resort option.

This is not a technical decision, is it? This is a political decision to promote this instance of the wiki as the *official one.

Foundation still retains the image dimension of the various official websites they are endorsing.

This is not really an issue on should we use that technology or this technology, this is really just about promoting a copy of nixos.wiki as an official wiki with a different administration team (:= political).

if they get blocked by any reason, which is why this was escalated there

I cannot remember or find any instance of this being blocked in any way before. If that actually exists, please link to it or give more context.

So to me it looks like it's absolutely not the foundation's decision.

There's a bunch of context across the years on the problem surrounding the old wiki, this was raised because there are multiple candidates for being promoted as an official wiki, I do not want to link to it because I don't want to shake the hornet's nest needlessly.

People have been working on this project at least for the last year, it was indeed blocked on "decisionmaking".

infinisil commented 5 months ago

@RaitoBezarius Fair, you make good points. So this is directly related to https://github.com/NixOS/foundation/issues/39, because we'd be setting the precedent that the NixOS foundation can decide over what is official. And I'm really not sure if I like that idea, because it doesn't involve the community much.

But we do have a way of deciding things officially that involves the community: RFCs. Yeah I know there's problems with RFCs, and I'm trying to improve it (stuck waiting for shepherds..), but that would really be the best way to do it then. And if you have shepherds, RFCs can be done in a couple weeks.

I'd be willing to either author/co-author or shepherd such an RFC. The issue description is pretty much in RFC format already, so it's very easy to do, and it seems like there's consensus around this already, so if we get some other shepherds this is gonna be a quick thing.

RaitoBezarius commented 5 months ago

@RaitoBezarius Fair, you make good points. So this is directly related to #39, because we'd be setting the precedent that the NixOS foundation can decide over what is official. And I'm really not sure if I like that idea, because it doesn't involve the community much.

I understand that feeling and I believe it is very much shared inside the Foundation, that is, we are already in a last-resort situation: the sad state of wiki is hurting a lot of folks and I think you are totally right that we need to separate this exceptional event and not reuse it as a precedent.

But we do have a way of deciding things officially that involves the community: RFCs. Yeah I know there's problems with RFCs, and I'm trying to improve it (stuck waiting for shepherds..), but that would really be the best way to do it then. And if you have shepherds, RFCs can be done in a couple weeks.

I still don't really agree (but I didn't have time to get back to you on other channels) with this framing of RFCs, Bootspec v2 is yet another excellent example, had plenty of shepherds, but the momentum is kind of killed.

I'd be willing to either author/co-author or shepherd such an RFC. The issue description is pretty much in RFC format already, so it's very easy to do, and it seems like there's consensus around this already, so if we get some other shepherds this is gonna be a quick thing.

All that I hope for is that this does not put further churn on people trying to get this somewhere, which is the real focus of the operations, not the excessive bureaucracy that we inflict ourselves for the sake of a governance that tends to burn out people in general, at least, for the time being. I would reserve it for more high stakes decisions, IMHO. Here, we are talking about deploying a wiki…

infinisil commented 5 months ago

I still don't really agree (but I didn't have time to get back to you on other channels) with this framing of RFCs, Bootspec v2 is yet another excellent example, had plenty of shepherds, but the momentum is kind of killed.

RFCs can have widely different scales. The bootspec one attempts to create a new version of a specification, with all its intricacies. This is no easy feat and takes time. As does the Nix formatting RFC, it's been in progress for over a year!

However for making the official wiki, there's really just these points:

This is very small in scope, which is why this could be done very quickly.

Really this could be the start of a policy for making projects official properly, the above three points seem fairly universal for that.

In fact the Nix formatting RFC has pretty much those exact points as well, indeed it's also about making something official.

mikunimaru commented 5 months ago

I think it would be ideal to be able to manage article content on github. The de facto center of the nixos community is github.

asymmetric commented 5 months ago

@infinisil @RaitoBezarius I see the point about involving the community and think it's important. We could try with an RFC and if it ends up stalling without controversy, have the Foundation take the decision. This would effectively delay the wiki by some weeks, which may or may not be a big issue.

In case we decide to go ahead with the RFC, I'd be available as a shepherd.

nixos-discourse commented 5 months ago

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

https://discourse.nixos.org/t/official-nixos-wiki/38715/5

zimbatm commented 5 months ago

Our Tuesday foundation meeting was pushed to today, where we briefly discussed this topic. We don't think we need to make a decision on this. We are here to unblock, and there is already a consensus on wiki.nixos.org. So let's go.

infinisil commented 5 months ago

@fricklerhandwerk @Lord-Valen Can you expand why you downvoted @asymmetric's comment? Because there's three separate mentioned points in it.

Regarding the foundations meeting, I think it's great that you aren't making a decision on this, but I'm not sure why people seem to celebrate that.

@Mic92 @Lassulus @RaitoBezarius @JulienMalka: My offer still stands, I can author or shepherd an RFC on this. If some of you and @asymmetric (or others in this thread) volunteer as shepherds, we can have an official shepherd team and initiate FCP immediately. Since there's widespread approval of this idea already I expect it to go through without hickups. Just let me know and I'll initiate it.

fricklerhandwerk commented 5 months ago

@Infinisil I downvoted because I'm against delaying it for more weeks. It took enough time as it is. There is no opposition, let's just do it.

Lord-Valen commented 5 months ago

I find that this isn't a subject worthy of an RFC and will only really serve to delay the wiki. The purpose of the RFC process is, as I understand it, to put "substantial changes" to the "nix ecosystem" through a design process and to produce a community "consensus."^rfc That seems to have already occurred since this is "widely accepted," and that there seems to be "some consensus."[^inf] That's made pretty clear since the only concerns that have been expressed were the apparent lack of community involvement (this is ironically community involvement in and of itself), all else has been emphatic support.[^huzzah]

[^inf]: https://github.com/NixOS/foundation/issues/113#issuecomment-1910785580; https://github.com/NixOS/foundation/issues/113#issuecomment-1920154591. [^huzzah]: https://github.com/NixOS/foundation/issues/113; https://discourse.nixos.org/t/official-nixos-wiki/38715.

Mediawiki is non-contentious (especially since we preserve the old wiki content) and the work is already done. Domain name concerns are bikeshedding. The Documentation and Infrastructure teams are onboard -- two teams I think would be most concerned with and responsible for wiki decisions, each in their respective scopes -- the Foundation team is non-blocking. Frankly, the path forward doesn't seem like it could be much clearer. So, I agree with @infinisil when he says "I think the next step is doing this!".^justdoit

infinisil commented 5 months ago

I'm against delaying it for more weeks. It took enough time as it is.

Yeah we knew about the problems with the old wiki for much longer, but this proposal came forth last week, there was never any delaying going on. And I don't think delaying this by a couple weeks matters at this point, there's no urgency to this.

That seems to have already occurred since this is "widely accepted," and that there seems to be "some consensus."2

The problem I have here is this seemingly arbitrary method of making decisions:

All of these points are addressed by RFCs:

[^1]: Traditionally Discourse, but future FCPs will also be announced on official social channels

So, I agree with @infinisil when he says "I think the next step is doing this!".4

Yeah I regret saying that now, I now really think this would be a great opportunity to establish a process for making something new official, which we are currently lacking. There's some really good candidates that could also make use of this.

lf- commented 5 months ago

The wiki discussion has been going on for some months, at least since a bit after NixCon. It's my understanding that it was not deliberately publicized, but was in a public space, in the interest of hopefully getting cooperation of the nixos.wiki maintainer, but since that is assumed not happening, this is something that really should just be moved on, since we do actually need a wiki, and the other one is undermaintained.

I don't see why there is any point in requiring an RFC for creating a new official project, since doing that would simply burn out maintainers even harder. This is not the process today, and until this, I don't think anyone was suggesting it.

Rust doesn't require RFCs to implement changes to the website structure or to create new projects. The equivalent process for this situation might be more like a MCP, in which a proposal is made, and it is accepted by the affected team, however, the affected team, in this case, is the group making the change here and has significantly discussed it

infinisil commented 5 months ago

Fwiw, I'm an active member of the documentation team and have not known about this proposal before this issue was opened. I'm on board, but please don't add people's approval without contacting them beforehand..

I don't see why there is any point in requiring an RFC for creating a new official project, since doing that would simply burn out maintainers even harder.

This reminds me of the merge bot attempt, which became somewhat official overnight without any sort of discussion beforehand, notably also by @Lassulus and @Mic92. That clearly showed that we shouldn't blindly accept projects as official. RFCs being hard isn't a good argument for not doing them.

I hate to be persuaded by upvote ratios, but I'm clearly in the minority and don't want to be a pain in the ass for everyone. So yes, I won't hold anybody back on this anymore, let's go. :rocket:

However, this should not serve as a precedent for how future decisions should be made. The RFC process sucks yes. It needs to be improved, and I'd like people to support me in that by nominating as shepherds (right now for https://github.com/NixOS/rfcs/pull/138, though it doesn't address the problem here), because otherwise we can't make improvements to it.

adamcstephens commented 5 months ago

However, this should not serve as a precedent for how future decisions should be made. The RFC process sucks yes. It to be improved, and I'd like people to support me in that by nominating as shepherds (right now for https://github.com/NixOS/rfcs/pull/138, though it doesn't address the problem here), because otherwise we can't make improvements to it.

I'm upvoting moving forward on this, but completely agree with this statement. I applaud your efforts and desire to make these processes formalized and better, and we should continue to strive towards improving things. I'd suggest that we consider this effort when thinking about those improvements. How can we unblock and enable teams to build new things under the NixOS umbrella, while providing proper community feedback mechanisms? The current RFC process feels onerous for an initiative such as this, so maybe there are criteria that either bypass the RFC process or provide a fast lane.

nixos-discourse commented 4 months ago

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

https://discourse.nixos.org/t/nixos-foundation-board-meeting-minutes-2024-01-02-2024-02-03/39994/1

sdht0 commented 3 months ago

So what's the next step towards getting this wiki up and running?

emanueljg commented 3 months ago

I want to preface this comment by saying that I think the wiki model of documentation is the best type of software documentation, period. I think the single biggest reason that Arch is so successful as a distro is its stellar wiki, which AFAIK is its single source of documentation; front-and-center both on the website and SEO. The goals of Arch, a fundamentally hobbyist OS, is obviously not the same as Nix(OS), but I felt it still warranted a mention.

That being said, I worry that the addition of an official wiki will scatter the documentation even further. To my knowledge, we would then have 6 official sources of documentation:

With the wiki that was unofficial, you could at least just tell new people "it's unofficial, go read the manuals instead". But with so many different sources of truth now, I worry that we are becoming too fractionated. And if this extreme orthogonality is really what we want, we should have very clear-cut guidelines on what info goes where.

As per nix.dev's own explanation (source) of it:

Fine. But my issue with this is that I can't see a niche for wiki articles here.

Where does the wiki fit in?

If the main reason for a wiki is "contributors don't need to go through the PR process and can just make edits directly" then I sympathize, but if so, how do you keep a steady influx of contributors to the manuals/nix.dev? I see no reason as to why you wouldn't just pick the path of least resistance as an aspiring contributor. I think there's strong reason to expect the three different sources of documentation to fall out of sync quickly, further exacerbating the issue of the project's documentation.

My 1st counter-proposal to the proposal of a wiki:

My 2nd counter-proposal: Nuke all other sources of documentation and set the wiki as the only one.

For the reasons I have laid out, I consider both of these options more healthy than the currently proposed one.

sdht0 commented 3 months ago

Well to me, a wiki is different from the others because of the informal "seek forgiveness rather than permission" model.

I'd have been happy with the existing wiki at https://nixos.wiki, but my attempts to make changes were blocked by the recent security measures. Plus it seems to be in a generally unmaintained state. So one benefit I'm expecting from this initiative is better ongoing maintenance.

The way I see it, the Arch wiki is so good because it has individual pages for each supported package, creating a single place where the community can collect everything there is to know about the package. And in general, there are two broad areas: installation + configuration and tip & tricks + troubleshooting. The NixOS modules and https://search.nixos.org actually cover the first area pretty well. But NixOS-specific knowledge in the second area is currently scattered all over. My hope is that the lower friction of wiki model will attract more contributions in this regard, so we can once and for all document solutions to the little issues that we encounter everyday and help others who might be facing the same.

Of course, we don't have to use a wiki. The current nix.dev is perhaps also a good alternative. The reason I like the wiki model is that it allows pages of varying quality. One person can start with some bare minimum content. Another person could come in just to add a warning indicating what is missing. Someone else could make a quick edit making it a tiny bit better. And so on.

emanueljg commented 3 months ago

The way I see it, the Arch wiki is so good because it has individual pages for each supported package, creating a single place where the community can collect everything there is to know about the package.

Then why have a manual that also documents said package?

And in general, there are two broad areas: installation + configuration and tip & tricks + troubleshooting. The NixOS modules and https://search.nixos.org/ actually cover the first area pretty well.

Installation & Configuration is already covered? I disagree. Consider the nginx module:

2024-03-14-065346_934x980_scrot

This is not quickstart documentation. It's module reference. The reason why its not quickstart-friendly dockumentation is that someone that is new to nginx and/or NixOS would view this as an impenetrable wall of text (which it is). Here's how a wiki works: 

# Nginx 

Nginx is a <blah blah blah>

## Basics 
You can use nginx to serve webpages. Here's how to serve one over http port 80:

_: { services.nginx = "insert comment-annotated configuration"; }

## SSL & Certificates
...etc...

It gives you a mental framework for chunking down all of the options, to highlight the most important basic ones, gives you a few different ways of combining the options, etc. When you then have a feel for the options, you can then go check the module reference for more in-depth info. The WireGuard page is the perfect example of this in my opinion. The more time you spend on NixOS, the more you can make educated guesses on how to configure any given option just by looking at said module reference, but that's a skill that takes a while to learn and will be virtually impossible for new people to do.

But NixOS-specific knowledge in the second area is currently scattered all over.

Is the answer to that further documentation dilution?

My hope is that the lower friction of wiki model will attract more contributions in this regard, so we can once and for all document solutions to the little issues that we encounter everyday and help others who might be facing the same.

Again, I don't see how that wouldn't just make the nix.dev and the manuals become instantly outdated compared to the wiki.

Of course, we don't have to use a wiki. The current nix.dev is perhaps also a good alternative. The reason I like the wiki model is that it allows pages of varying quality. One person can start with some bare minimum content. Another person could come in just to add a warning indicating what is missing. Someone else could make a quick edit making it a tiny bit better. And so on.

I don't think it's a good idea to allow plurality in this space. We have to come down on one side or the other, or it's a lose-lose for both.

beh-10257 commented 3 months ago

As a user of nix (for like a year but I have been following this for while and I might as well say what I want its not like its gonna change something) To be honest the biggest hurdle is not using pull requests to add documentation its not finding it and having to go to a couple of discord servers Just pick one between nix.dev and nixos.wiki And at that point I don't understand the point of manuals just port the manual sections into pages in nix.dev And to be honest I am with migrating everything into nix.dev since well its nicer and I found the documentation there much better

Also you should consider somehow linking the wiki to seach.nixos.org somehow like when I search for webcord or something and there is a wiki page about it suggest it Also for exemple if I document something random lib.replacestr (I'm not sure of the name I'm typing on a phone and my pc is an hour away) than add an option to make the thing I documented seachable in search.nixos.org To be honest I don't really understand the point of a manual if I can't even search natively and have to use google or something just deprecate it

Anyway sorry for showing up even though I have nothing to do with the documentation team

lf- commented 3 months ago

we do need a place for horrible garbage workarounds that nobody wants to own up to. a wiki is unfortunately necessary. also the modules documentation doesn't have any way to describe the module itself at the moment or like, common configurations.

either we need per module pages in some manual or a wiki.

but you still need some place for the horrible workarounds you don't admit to having.

beh-10257 commented 3 months ago

@lf- for example I have a workaround for making themes and icons and cursors work in flatpaks This topic isn't even in the arch wiki I guess Like Its even better than arch wiki since well I can't change themem pkg and no need to change the workaround

Anyway as I said nix.dev is great just have a vote or something

Also if the manuals are gonna stay here make them searchable

sdht0 commented 3 months ago

Then why have a manual that also documents said package?

Yeah the configuration section of the NixOS manual is what currently exists but quite incomplete (has a seemingly random selection of packages). Also the manual interface has some limitations as of today. It loads the whole manual at once, which will be less practical as more content is added. And it is not SEO friendly. Searches for "nixos gnome" links to the wiki but the manual doesn't even appear.

This is not quickstart documentation.

Sorry didn't mean to imply that it is ideal. Just that if one knows how to read nix code, the module links can help one know every configuration that is available to the user (code as documentation). But practical issues (such as figuring out why my chromium is unable to hardware accelerate video decoding) currently do not have a go-to place for solutions.

Is the answer to that further documentation dilution? Again, I don't see how that wouldn't just make the nix.dev and the manuals become instantly outdated compared to the wiki. I don't think it's a good idea to allow plurality in this space. We have to come down on one side or the other, or it's a lose-lose for both.

Well, the status-quo is that there is already a unmaintained wiki that tops nixos-related searches and hopefully this new better maintained wiki can subsume that at the very least. And if the community can actually rally around the wiki, then sure these other documentations can be moved to the wiki where appropriate. We should give it a (second) shot.

Anyway I don't want to add more noise to the thread. I was just hoping a decision can be made in either direction.

zimbatm commented 3 months ago

Let's see what happens. The wiki team is working on it and should be up soon. In any case, the hardest bit is to get to a place where we have good documentation, and that takes a lot of love and dedication. Once we have the content, we can always shift it around.

wrycode commented 3 months ago

Another vote here for moving it all into one place: the wiki(s), the manual, and anything else that is appropriate. I would love to see a canonical place for documentation and a clear process for making changes.

Also don't underestimate the value of small edits and improvements by people who are new to the community and reading these documents for the first time.

Happy to see this area being worked on.

JulienMalka commented 3 months ago

The wiki has been launched: https://wiki.nixos.org

sdht0 commented 3 months ago

Perhaps https://wiki.nixos.org/wiki/NixOS_Wiki:History needs more revisions :)

JulienMalka commented 3 months ago

A lot of things need more revisions, but that's as easy as logging in and clicking the "edit" button :)

nyabinary commented 3 months ago

We need translations added soon hopefully so we can contribute community made translations :3