Add documentation vision

[friedow]

As part of the revival of the documenation team @hsjobeki and me have drafted a new vision for
the NixOS documentation. Based on this we will launch efforts to restructure the current documentation as well as a funraising campaign to finance those efforts.

Here is a small teaser:

Our vision extends toward a unified documentation portal that clearly separates reference material from practical guides, organized by ecosystem for easy navigation. We’re working to consolidate scattered resources, reduce duplication, and establish a single source of truth for the community. The roadmap includes prioritized getting-started guides for common workflows like installation, package management, and system recovery. We also distinguish between curated documentation and the community wiki, allowing each to serve its distinct purpose. Together, these efforts aim to lower barriers for newcomers while preserving the depth experienced users rely on.

For more details read the diff ;)

FYI: @roberth, @infinisil

[fricklerhandwerk]

I strongly approve the general direction, and read this as a reinforcement/rejuvenation of the docs team effort I've been part of in previous years!

Some side notes:

• Do you have the STF proposal for improving Nixpkgs documentation on your radar?

  Most items there are still relevant and still didn't get done.

• Have you considered the https://ngi.nixos.org approach for per-application documentation?

  You currently don't see much because the UI has been a background topic there, but if you check a sample you'll notice that a working (tested!) VM example and a productive example are generated automatically from the source. We're also listing which artefacts exist (i.e. work), such as these samples, and link to documentation for contributing if they don't.

  Note: It's deliberately designed that way as a prototype solution to NixOS documentation maintenance problems.

• Don't underestimate the scope and complexity of "moving things where they belong". I would say we failed at that ambition in the previous generation, and at best scratched the surface; it's just too much stuff and the quality is too much all over the place. I understand your approach is to mobilize component maintainers, and wish you the best of success with that; likely you (someone from docs) will have to spend at least as much as time as all of them combined, I strongly recommend accounting that in your funding proposals and capacity planning.

• What are your plans for generating reference docs from source and testing guides?

  @hsjobeki already did a pile of work for doc comments, which covers part of the first (Nixpkgs functions, but not NixOS modules), but I have yet to see getting the second off the ground (but have tried various prototypes).

  For NixOS modules, we do have multiple implementations for listing options, all of which don't really satisfy me for two reasons:

  • It's very hard to get an overview, because you either get a full list of options + docs, or can search for options. So you have to know to know; this doesn't work for beginners. (I've seen @hsjobeki did some cool things there for docs.clan.lol, so I assume you have some ideas)

    One thing I imagine would be search/list by application or system "component" (say, boot), and a by default collapsed list of options as there once was in https://github.com/tweag/jupyenv (the website is down atm. for some reason, I liked @djacu's implementation a lot). Typically this list wouldn't be large per application.

  • Modules have very little metadata, but typically as a user you need a lot of extra information to make sense of what's going on to even start using them. Recenltly @infinisil worked on adding meta.maintainers to modules, that's one step. But then it would also be nice to have proper links to upstream documentation for what the option covers; this is primarly an content addition issue, but it also needs to have the right data structure and rendering (e.g. links between module options; nixos-render-docs has syntax but IIRC we're not doing anything with that).

• What are your plans for search?

  The classical problem with search is that users typically search for an "application" (which may be an executable or desktop thingy, or a service) but input it in the wrong search type. Textbook example: user typing nginx into search.nixpkgs.org and getting the nginx package which is useless without the module. I'd like this to end.

  We started experimenting with some of that in ngi.nixos.org and I think it took a very good direction, but it needs more work and, most importantly, scaling up (facilitating adoption among maintainers), upstreaming, and using the exposed data in downstream tools such as search.

• What are your plans for onboarding new contributors?

  From experience, the Get Together approach of doing something together repeatedly works best out of everything we tried during my time, but it's more of an agile sort of thing where you don't know where you'll end up when you start.

[fricklerhandwerk]

And probably a set of well-supported applications as well? Or do you intend to have that covered by the wiki?