lix-project/lix

Fork

You've already forked lix

Code Issues 516 Code Review (Gerrit) Projects 8 Releases Packages Wiki Activity

Rewrite the Manual #779

New issue

Closed

opened 2025-03-29 22:08:57 +00:00 by kfearsoff · 4 comments

kfearsoff commented

2025-03-29 22:08:57 +00:00

Member

Copy link

Problem Statement

Lix manual functions alright as a reference point. It is nowhere near perfect for that, as there are many cursed intricacies that you'll only learn in code or in conversations, but it at least does its basic job.

Lix manual as generic documentation, though? It is very, very bad. A very large amount of issues are inherited from CppNix manual, and a number of issues Lix manual more or less fixed - for example, installation chapters are just deferred to the installer! But the overall situation is dire: Lix manual does not help the user actually use the software, at all.

This manual problem stems from the culture around Nix Project, where Nix/Nixpkgs/NixOS manuals were separate manuals with strongly defined boundaries. They were extremely isolated (perhaps mirroring the projects themselves, to a degree), and efforts to have them do more cross-references were unsuccessful.

We are in a unique position where we actually own Lix manual, so we can do it justice and make it a great piece of user-facing documentation.

Scope of Work

Rewrite introduction. For now, our new users are 95% Nixers with some experience, 5% brand new people. The distribution will change with time. How do we write a useful introduction for all of them? Could we use an approach similar to Rust Book's "who Rust is for?"
Right now, we can't even provide a proper "Quick Start", because our "install" semantics are terrible. What to do? We can copy CppNix's nix-shell-based "Quick Start". We could also drop "Quick Start" entirely, like Rust Book does.
Our section on installation is absurdly large. Compilation instructions should go to repo; installation instruction should defer to installer and be compressed.
Until we figure out our "install" semantics - our "Package Management" section should guide people on how to set up a sane workflow: probably npins, HM and/or nix-darwin.
We should have a section on guiding the user through "building" process. How does a typical derivation look? How is it built and cached? How does NixLang play into that, and how to "grok" it fast? This needs to be an actual section.
NixLang reference and spec should be moved way down. No user would care about operator precedence and derivation attributes outside of reference material; and since mdbook doesn't support fold-by-default, it should be moved down.
Likewise, command reference takes up screens. It should be at the bottom.
Documenting builtins, config files and other stuff should be done together.
In terms of "advanced topics" - there's a lot that can be added, but let's just backport IFD docs PR for now.
Glossary is... not useless, but it is also a crutch. Currently, the manual relies very much on definitions given in the glossary - and those definitions use 10 other definitions, go in circles, and explain nothing. This is horrible UX. Our terms should not be oppressively unfamiliar. NixLang code = "build recipe", "derivation" = "build plan", "build plan" produces outputs/artifacts. Jujutsu Glossary is a good kind of glossary - it uses established terminology, and glossary just expands on the topic.
"Contributing" and "Release Notes" should probably live in the repo, but not in the manual

Additional context

Sadly, I don't think it is possible to improve the manual perfectly iteratively, unless we make gigantic CLs/divide them using "topics". Its structure is very unfortunate.

We also really want #742 first.

## Problem Statement Lix manual functions alright as a reference point. It is nowhere near perfect for that, as there are many cursed intricacies that you'll only learn in code or in conversations, but it at least does its basic job. Lix manual as generic documentation, though? It is very, very bad. A very large amount of issues are inherited from CppNix manual, and a number of issues Lix manual more or less fixed - for example, installation chapters are just deferred to the installer! But the overall situation is dire: Lix manual does not help the user actually use the software, at all. This manual problem stems from the culture around Nix Project, where Nix/Nixpkgs/NixOS manuals were separate manuals with strongly defined boundaries. They were extremely isolated (perhaps mirroring the projects themselves, to a degree), and efforts to have them do more cross-references were unsuccessful. We are in a unique position where we actually own Lix manual, so we can do it justice and make it a great piece of user-facing documentation. ## Scope of Work - [ ] Rewrite introduction. For now, our new users are 95% Nixers with some experience, 5% brand new people. The distribution will change with time. How do we write a useful introduction for all of them? Could we use an approach similar to Rust Book's ["who Rust is for?"](https://doc.rust-lang.org/book/ch00-00-introduction.html#who-rust-is-for) - [ ] Right now, we can't even provide a proper "Quick Start", because our "install" semantics are terrible. What to do? We can copy CppNix's `nix-shell`-based "Quick Start". We could also drop "Quick Start" entirely, like Rust Book does. - [ ] Our section on installation is absurdly large. Compilation instructions should go to repo; installation instruction should defer to installer and be compressed. - [ ] Until we [figure out our "install" semantics](https://wiki.lix.systems/books/lix-contributors/page/replacement-cli-design-profiles) - our "Package Management" section should guide people on how to set up a sane workflow: probably npins, HM and/or nix-darwin. - [ ] We should have a section on guiding the user through "building" process. How does a typical derivation look? How is it built and cached? How does NixLang play into that, and how to "grok" it fast? This needs to be an actual section. - [ ] NixLang reference and spec should be moved way down. No user would care about operator precedence and derivation attributes outside of reference material; and since mdbook doesn't support fold-by-default, it should be moved down. - [ ] Likewise, command reference takes up screens. It should be at the bottom. - [ ] Documenting builtins, config files and other stuff should be done together. - [ ] In terms of "advanced topics" - there's a lot that can be added, but let's just backport IFD docs PR for now. - [ ] Glossary is... not useless, but it is also a crutch. Currently, the manual relies very much on definitions given in the glossary - and those definitions use 10 other definitions, go in circles, and explain nothing. This is horrible UX. Our terms should not be oppressively unfamiliar. NixLang code = "build recipe", "derivation" = "build plan", "build plan" produces outputs/artifacts. [Jujutsu Glossary](https://jj-vcs.github.io/jj/v0.27.0/glossary/) is a good kind of glossary - it uses established terminology, and glossary just expands on the topic. - [ ] "Contributing" and "Release Notes" should probably live in the repo, but not in the manual ## Additional context Sadly, I don't think it is possible to improve the manual perfectly iteratively, unless we make gigantic CLs/divide them using "topics". Its structure is very unfortunate. We also really want #742 first.

kfearsoff added the

labels

2025-03-29 22:08:57 +00:00

kfearsoff added this to the Docs rewrite project

2025-03-29 22:08:57 +00:00

jade commented

2025-04-01 00:25:40 +00:00

Owner

Copy link

This manual problem stems from the culture around Nix Project, where Nix/Nixpkgs/NixOS manuals were separate manuals with strongly defined boundaries. They were extremely isolated (perhaps mirroring the projects themselves, to a degree), and efforts to have them do more cross-references were unsuccessful.

FWIW it still probably is proper for Lix's manual to not try to be more things than it actually has resources to be. However, it should talk more about how Lix is only made particularly useful in the context of nixpkgs.

Glossary is... not useless, but it is also a crutch. Currently, the manual relies very much on definitions given in the glossary - and those definitions use 10 other definitions, go in circles, and explain nothing. This is horrible UX. Our terms should not be oppressively unfamiliar. NixLang code = "build recipe", "derivation" = "build plan", "build plan" produces outputs/artifacts. Jujutsu Glossary is a good kind of glossary - it uses established terminology, and glossary just expands on the topic.

We could take some terminology from that, and discuss synonyms.

"Contributing" and "Release Notes" should probably live in the repo, but not in the manual

Release notes should be in the manual because they have a nasty habit of being the complete documentation for features and are really important to catch in search queries. Contributing should plausibly be moved.

Another thing that has been annoying me with the manual is that mdbook does not prioritize page titles in search. I wonder if we can convince it to behave better in this regard.

> This manual problem stems from the culture around Nix Project, where Nix/Nixpkgs/NixOS manuals were separate manuals with strongly defined boundaries. They were extremely isolated (perhaps mirroring the projects themselves, to a degree), and efforts to have them do more cross-references were unsuccessful. FWIW it still probably is proper for Lix's manual to not try to be more things than it actually has resources to be. However, it *should* talk more about how Lix is only made particularly useful in the context of nixpkgs. > Glossary is... not useless, but it is also a crutch. Currently, the manual relies very much on definitions given in the glossary - and those definitions use 10 other definitions, go in circles, and explain nothing. This is horrible UX. Our terms should not be oppressively unfamiliar. NixLang code = "build recipe", "derivation" = "build plan", "build plan" produces outputs/artifacts. Jujutsu Glossary is a good kind of glossary - it uses established terminology, and glossary just expands on the topic. Agreed, see also: https://archive.fosdem.org/2024/schedule/event/fosdem-2024-3107-units-of-composition-recipes-overlays-and-packages/ We could take some terminology from that, and discuss synonyms. > "Contributing" and "Release Notes" should probably live in the repo, but not in the manual Release notes should be in the manual because they have a nasty habit of being the complete documentation for features and are really important to catch in search queries. Contributing should plausibly be moved. --- Another thing that has been annoying me with the manual is that mdbook does not prioritize page titles in search. I wonder if we can convince it to behave better in this regard.

patka-123 commented

2025-04-01 05:05:40 +00:00

Copy link

... mdbook does not prioritize page titles in search.

This can be achieved with the boost-title option. I'm currently on vacation, but can send the change in about a week, if not picked up by somefew in the meantime.

(I'll also create a seperate issue and stop hijacking this one)

> ... mdbook does not prioritize page titles in search. This can be achieved with the [boost-title](https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlsearch) option. I'm currently on vacation, but can send the change in about a week, if not picked up by somefew in the meantime. (I'll also create a seperate issue and stop hijacking this one)

👍 1

kfearsoff commented

2025-04-01 16:05:20 +00:00

Author

Member

Copy link

FWIW it still probably is proper for Lix's manual to not try to be more things than it actually has resources to be. However, it should talk more about how Lix is only made particularly useful in the context of nixpkgs.

Right. My current idea is to defer things like "learn NixLang" and "DIY packaging" to https://nix.dev with links in the manual. It'll take some effort to make a good segue, but I'm confident it can be done and is a good idea.

Glossary is... not useless, but it is also a crutch. Currently, the manual relies very much on definitions given in the glossary - and those definitions use 10 other definitions, go in circles, and explain nothing. This is horrible UX. Our terms should not be oppressively unfamiliar. NixLang code = "build recipe", "derivation" = "build plan", "build plan" produces outputs/artifacts. Jujutsu Glossary is a good kind of glossary - it uses established terminology, and glossary just expands on the topic.

Release notes should be in the manual because they have a nasty habit of being the complete documentation for features and are really important to catch in search queries.

Geh, you're right. Perhaps some wizard can figure out how to fold that section (and command reference) by default, cos the amount of screen space taken is very uncomfortable.

Contributing should plausibly be moved.

I think it should, yeah. We currently have contributing info spread out over git repo, Wiki, and manual. I don't know the right distrubution yet, but I think cutting the manual is a good idea.

See CL#2924 for the first baby steps.

> FWIW it still probably is proper for Lix's manual to not try to be more things than it actually has resources to be. However, it _should_ talk more about how Lix is only made particularly useful in the context of nixpkgs. Right. My current idea is to defer things like "learn NixLang" and "DIY packaging" to https://nix.dev with links in the manual. It'll take some effort to make a good segue, but I'm confident it can be done and is a good idea. > > > Glossary is... not useless, but it is also a crutch. Currently, the manual relies very much on definitions given in the glossary - and those definitions use 10 other definitions, go in circles, and explain nothing. This is horrible UX. Our terms should not be oppressively unfamiliar. NixLang code = "build recipe", "derivation" = "build plan", "build plan" produces outputs/artifacts. Jujutsu Glossary is a good kind of glossary - it uses established terminology, and glossary just expands on the topic. > Release notes should be in the manual because they have a nasty habit of being the complete documentation for features and are really important to catch in search queries. Geh, you're right. Perhaps some wizard can figure out how to fold that section (and command reference) by default, cos the amount of screen space taken is very uncomfortable. > Contributing should plausibly be moved. I think it should, yeah. We currently have contributing info spread out over git repo, Wiki, and manual. I don't know the right distrubution yet, but I think cutting the manual is a good idea. See [CL#2924](https://gerrit.lix.systems/c/lix/+/2924) for the first baby steps.

jade referenced this issue

2025-04-02 03:13:45 +00:00

Search in the manual is terrible #785

jade commented

2025-04-02 03:14:15 +00:00

Owner

Copy link

Opened an issue about search being useless.

kfearsoff closed this issue

2025-05-10 13:57:09 +00:00

No Branch/Tag specified

main

ci-config

release-2.91

release-2.92

release-2.93

sb/raito/darwin-kqueue-disablement

sb/raito/hydra-merge

sb/pennae/ci-config

sb/raito/phantom-referrers-gc

repl-overlay-example

reuse-compliance

release-2.90

sb/pennae/io-rewrite

git-series/activity-cleanup

sb/tom-hubrecht/primops.cc-v2

sb/bacchanalia/cache-strlen%topic=substr-perf

sb/qyriad/beta-1

sb/qyriad/2.90-beta.0

sb/rbt/test-branch

sb/rbt/justfile

sb/rbt/repl-overlays

sb/qyriad/maint-meson

sb/qyriad/maint/meson

sb/puck/meson-c-api

sb/jade/burn-it-all

dependabot/github_actions/zeebe-io/backport-action-2.4.1

dependabot/github_actions/cachix/install-nix-action-25

dependabot/github_actions/actions/labeler-5

dependabot/github_actions/cachix/cachix-action-14

2.93.3

2.92.3

2.93.2

2.91.3

2.92.2

2.91.2

2.93.1

2.93.0

2.92.0

2.91.1

2.91.0

2.90.0

2.90.0-rc1

2.90-beta.1

2.90-beta.0

Labels

Clear labels

Affects/CppNix

Probably affects CppNix. This is a best-effort tag for troubles in old code; it exists to inform the CppNix team about problems they might care about also.

Affects/Nightly

Found in Lix nightly.

Affects/Only nightly

Tag for regressions in Lix nightly. We intend to fix all of these prior to releases.

Affects/Stable

Affects the stable release of Lix. Usually such issues affect nightly too but there is no guarantee.

Area/build-packaging

regarding the building or packaging of Lix itself

Area/cli

The command line interface of Lix

Area/evaluator

libexpr and anything else related to the evaluation of Nix expressions

Area/fetching

Fetching sources or other materials from the World Wide Web in Lix

Area/flakes

Area/language

language design, features, extensions, etc

Area/lix ci

Lix's own CI and deployment pipeline

Area/nix-eval-jobs

nix-eval-jobs for Lix

Area/profiles

profiles: nix-env, nix profile, and installer flavors all alike

Area/protocol

The protocol, used for communicating between the client and the daemon

The --debugger that brings up a Lix repl

Area/store

libstore and anything else relating to the Nix store

This issue might require some context that isn't written down. It might be possible to handle as a person who already worked on this area.

Context

drive-by

This issue contains all the necessary information to do a drive-by contribution: that is, you don't have to talk with anyone at all to successfully solve it!

Context

maintainers

This issue requires a lot of know-how. Attention from maintainers is needed to proceed.

Context

RFD

This issue needs discussion from multiple maintainers and interested parties: it's a Request For Discussion.

crash 💥

Lix crashes (possibly bad error handling)

Cross Compilation

devx

development experience issues

docs

requires or is about documentation changes

Downstream Dependents

regarding an external tool's usage with Lix (e.g. nix-eval-jobs)

E/easy

bug is relatively simple and could simply be fixed with some minor effort

E/hard

this issue should probably be solved with close involvement of an expert

E/help wanted

maintainers may not get to this soon, but we want it fixed

E/reproducible

This bug is reproducible and obvious.

E/requires rearchitecture

this bug cannot be fixed properly without fixing a known architectural flaw

imported

Issue imported from upstream nix (please do not remove this label, it will cause dupes if import is rerun)

We can't get to this until we implement language versioning

OS/Linux

Affects specifically Lix on Linux

OS/macOS

Affects specifically Lix on macOS

performance

make lix go faster

regression

This is a regression since some previous version of Lix

release-blocker

Blocks public release

stability

Fixing this makes the software more stable

not our bug, duplicate, similar

Status

postponed

closed but should maybe look at later (generally with S-wontfix)

Status

wontfix

We chose not to change this (see issue comments for more detail).

testing

Tests that should be added

testing/flakey

Tests that are unreliable/flakey (not to be confused with flakes that test)

Topic/Large Scale Installations

Large scale installations of Lix, e.g. NixOS Hydra, Lix CI, big corporate installations etc.

makes the user experience better :)

No labels

Downstream Dependents

E/requires rearchitecture

Topic/Large Scale Installations

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Docs rewrite

Assignees

Clear assignees

No assignees

3 participants

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: lix-project/lix#779

Reference in a new issue

Repository

lix-project/lix

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns