Apart from the initial literature survey, I ran a a small usability study: https://discourse.nixos.org/t/usability-studies/21404 and evaluated the community polls: https://discourse.nixos.org/t/2022-nix-survey-results/18983

When the documentation team was founded the current strategy evolved based on the following considerations:

• nix.dev existed and was the highest quality overview resource out there, the Wiki existed and had the broadest coverage with varying quality - we shouldn’t start from scratch, also for discoverability purposes, so the book idea was dropped in favor of eventually developing nix.dev into that book eventually, incorporating useful bits from the wiki
• the system surface was enormous and messy, so improving everything at once under a somewhat consistent paradigm was (and still is) impossible. We had to focus on a meaningful and most impactful subset
• some things have to be figured out how to even use properly, or even fixed in the code before one can write any documentation. And before writing a tutorial or guide, one needs proper reference documentation. Often that’s lacking, we’ve experienced that for every piece we worked on.
• the most important part for user retention is onboarding and contributing. The only thing usable in isolation is Nix itself.

So this is what we did and are still doing, and we’re quite far advanced with improving the documentation relevant for the first couple of weeks using vanilla Nix. I don’t have the numbers to prove it, but from anecdata and heuristics about the types of questions asked on Discourse, I think we managed to substantially reduce the average initial onboarding time and fraction of people who give up before concluding that.

And even that took what feels like forever, because we ran into many obstacles that relate to governance issues. The first impressions are highly exposed material and so I have to get change proposals past people who have authority over the pieces in question. That’s another reason why we focus on nix.dev more than anything else: the documentation team has free reign over it (within the constraints of not breaking things that already worked for people).

Which means that still, NixOS and Nixpkgs documentation have barely improved in the meantime. We here know all the issues with it, but dealing with them takes time that’s taken away from the original mission. We’re trying to balance that, because not supporting attempts at contributions is of course frustrating for everyone.

What we really need are dedicated maintainers for the various sections of the Nixpkgs manual, all of the NixOS manual, and ideally editors for the (upcoming new) Wiki. This stuff is up for grabs, and I’d definitely recommend org owners to hand out commit bits to anyone who demonstrates they understand and subscribe to the general direction we’re taking. So far no one stepped up, and those who considered, reconsidered again after dipping their toes into the intricacies of the stuff actively being worked on.

We first have to get the basics right before piling stuff on top. There’s already way too much stuff piled up, and the basics are still not in a great shape.

In reply to @infinisil:matrix.org
Needs a unified docs building infrastructure though

In reply to @9999years:matrix.org
those PRs look great! what's blocking them from being merged?

In reply to @asymmetric:matrix.dapp.org.uk
btw, we have ~60 prs in nixpkgs that are about documentation, but have no 6.topic: documentation label, including some by mebers of this team. i think it would be helpful to ensure that label is added, so we can triage them instead of letting them rot.

hmm, the label description says "Meta-discussion about documentation and its workflow", so maybe i'm wrong that it should be applied to those prs?

should documentation PRs have that label, or not?

In reply to @infinisil:matrix.org
asymmetric: Sounds like the label description should be updated then :)

In reply to @infinisil:matrix.org
I feel like the content vs infra distinction sounds better

In reply to @infinisil:matrix.org
I feel like the content vs infra distinction sounds better

Just went through a rabbithole when creating a PR, and have a few questions that I think would be better asked here rather than spending even more time trying to dig things:

1. Does anyone know why a bunch of places in our docs use the shellSession/ShellSession info on code blocks? https://github.com/search?q=repo%3ANixOS%2Fnixpkgs%20shellsession&type=code
   From my investigation, it seems to be ignored by the highlighting library we use in the manuals
2. A look into the highlighting library used in the manuals makes me believe that the unstable manuals haven't been updated in nixos.org for at least 2 months (library was updated from v9 to v11 ~2mo ago, but the version used in nixos.org is still v9). I can't spend more time today looking into this, but I think this isn't normal. Did something break in the manual -> nixos.org pipeline?

In reply to @danielsidhion:nixos.dev

Just went through a rabbithole when creating a PR, and have a few questions that I think would be better asked here rather than spending even more time trying to dig things:

1. Does anyone know why a bunch of places in our docs use the shellSession/ShellSession info on code blocks? https://github.com/search?q=repo%3ANixOS%2Fnixpkgs%20shellsession&type=code
   From my investigation, it seems to be ignored by the highlighting library we use in the manuals
2. A look into the highlighting library used in the manuals makes me believe that the unstable manuals haven't been updated in nixos.org for at least 2 months (library was updated from v9 to v11 ~2mo ago, but the version used in nixos.org is still v9). I can't spend more time today looking into this, but I think this isn't normal. Did something break in the manual -> nixos.org pipeline?

Run bash ./scripts/update.sh
Updating flake inputs...
error: unrecognised flag '--update-input'
Try 'nix --help' for more information.
Error: Process completed with exit code 1.

Wait what, the current latest version is 2.19.2, which does have a deprecation message (tried it locally):

warning: '--update-input' is a deprecated alias for 'flake update' and will be removed in a future version.