2023-05-18 - Learning Journey Working Group - Meeting Notes #9

I am inclined to agree with @fricklerhandwerk, and perhaps go even further.

I believe trying to write good tutorials before we have good reference documentation is highly inefficient. Learning materials are, by their nature, linear/single-threaded, narrative, opinionated, contentious, etc. It is hard to decide what to do, and it is hard to subdivide the work among multiple people because the narrative structure requires such tight integration and unified vision.

Reference docs on the other hand are totally the opposite. They support random access, and are dry, unopinionated, uncontenious, etc. This makes divvying up the work very easy.

For example, see my Expanding tests and docs relating to deleting profiles by Ericson2314 · Pull Request #8351 · NixOS/nix · GitHub. There is basically one contentious bit here — is some behavior so unstable that it is dangerous to document it at all? — everything else is quite cut and dry. The only interaction between sections is hyperlinking, but we can do that post-hoc, or use the glossary to support outgoing links to material that has yet to be written.

That PR covers just two of dozens of commands. It should be easy to get a bunch off people to work on more such PRs in parallel. Yes, you have to read the code to double check what exactly things do — or at least I did :slight_smile: — but that shouldn’t be too hard.


I have not been involved with the docs team except for shadowing a meeting or two, and I haven’t been to a learning journey working group meeting at all. So take the above with a big fistful off salt — it is based on the theory of the task at hand, not first-hand experience with the groups of people actually tackling it.

Also I know most contributors or would-be contributors are much more excited about and motivated by tutorial and educational material. So sure, by all means start with what you love. But if anyone feels stuck, or the leaders feel like they have more volunteers than they know what to do with, I urge reallocating person-time to reference documentation efforts.

And with the references docs overhauled, the educational material will have a much sturdier foundation upon which to be a glorious shiny building.

4 Likes