In May 2022 I proposed a Summer of Nix project to work towards The Nix Book, a vision of unified learning material on everything Nix.
Originally, part of the undertaking was a set of survey questions to direct our activities:
- Which questions do newcomers ask most, and do they find satisfactory answers consistent with best practice?
- Which material should we add?
- How should we reorganize existing material?
- How should we improve existing material?
The most immediate answer to these questions could be found by observing users in practice. Hence, this is what I set out to do.
Procedure
- find a Nix beginner
- sit down for ~1h with screen sharing
- instruct them to think and read aloud
- observe them working with Nix on whatever they care about at the moment
- do not answer any questions (only after the session, for catharsis)
- only interfere or change course if they get stuck for too long, or if problems lead away from interacting with beginner-oriented documentation
- take notes on everything they say and do
- edit field notes for readability
@toraritte picked up the field notes to get them into shape, by removing personally identifiable information, rewording them to be easily readable, and adding context and links. Thank you so much! It cannot be stressed enough that without your help this would not have been possible.
Note that in such usability tests, usually one would want to have even more controlled conditions by specifying a set of tasks for all participants to perform. In these initial sessions I deliberately chose to take a more exploratory approach in order to document a range of use cases and the participants’ levels of expertise.
Session transcripts
- session #1
- session #2
- session #3
- session #4
- session #5
- session #6
- session #7
- session #8
- session #9
- session #10
Next steps
In the following weeks, we will file the issues encountered by study participants on GitHub, and link them in the transcripts. This way maintainers can keep track of them and prioritize accordingly. For readers it should then be obvious which of them have already been addressed.
Nix is a community project. You can help! When reading through a transcript you encounter a problem the user had, please check if there is an issue or pull request (which may be already closed!) on the respective resource. If not, please open an issue, or directly propose a change with a pull request. Each session is a Discourse wiki, which anyone can edit to link the issue or pull request in question.
See How to contribute to documentation to find the respective source repositories.
Funding
This effort is sponsored by Tweag (@fricklerhandwerk) and NLnet (@toraritte via 2022 Summer of Nix).