document store objects in terms of their constituent parts

[fricklerhandwerk]

this also rephrases the introductory sentence to be more general, in order to
avoid the same word being repeated in short succession.

Motivation

This is another step to finally implement #6420, and also serves as the documentation part of NixOS/rfcs#134

Priorities

Add 👍 to pull requests you find important.

[Ericson2314]

I think store objects should go on their own page. I would like to keep this first page abstract a definition of purpose. We can make it more normally sized by talking about things like

• building (sandboxing)
• purity
• multiple stores / distribution of data and computation)

I think we would end up with a pretty good statement of purpose that situations the rest of the pages which document the nitty gritty details --- the user that goes on to read those pages can get some intuition why things are the way they are. Ideally, that means the nitty-gritty details, rather than being something the user might work hard to memorize (unless they just want to refer back to the manual) are something becomes a "ah, but of course, why would it be any other way" and are more effortlessly remembered.

[fricklerhandwerk]

We can still move things around. Right now we have substantial pages on store paths and hashing in the pipeline. I suggest expanding this page here with things we have until they become large enough to warrant their own page.

[Ericson2314]

I really do not think that it is good to temporarily collapse the structure like that. We might know what sections we want to bubble out to other pages later, but other contributers will have no idea.

I strongly believe the surperioe model is making a bunch of small pages to later be expanded, because of how it facilitates large-scale collaboration. The "backbone" of the docs is the table of contents, which is planned out by the documentation leaders just as authors start with outlines. Then other contributers can find a small page and add more information.

It's very hard to crowd source and outline — there is too much coordination overhead, and by not yet any shared vision. Conversely, once we have an outline, it is the shared vision. And then it's really easy for a bunch of people to independently come to understand that outline/shared vision, and then procede to also independently work on specific sections.

[fricklerhandwerk]

Triaged in Nix team meeting:

• Overall goal coordinated with @Ericson2314 is to have multiple short pages for an outline that we can flesh out as we go
  • This will also make it easier to contribute to, as the structure will be self-explanatory
  • Small incremental changes, more asynchronous
• Idea approved to proceed that way

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-10-27-nix-team-meeting-minutes-98/34695/1

[roberth]

We may consider expanding the definition of store object to include other metadata, but this is definitely a good starting off point, if not already complete. E.g. we may consider such information to live outside the store object in some other concept that merely relates to a store object.