Nix is an open source build system, a configuration management system, and a mechanism for deploying software, focused on reproducibility. It is the basis of an ecosystem of exceptionally powerful tools – including Nixpkgs, the largest, most up-to-date software repository in the world, and NixOS, a Linux distribution that can be configured fully declaratively. Nix exists since 2003 and today is leveraged and relied upon by many professionals and organisations who recognise its value in the software development lifecycle.
The NixOS Foundation was founded in 2015 to shepherd the Nix ecosystem, and is dedicated to supporting volunteer teams in their activities.
The Nix documentation team was established in mid 2022 in order to ease learning Nix for beginners and support community efforts in that direction. Recently the team has gained many new members eager to tackle long-standing issues.
From the perspective of the NixOS Foundation, a concerted effort can help the Nix documentation team to substantially improve a crucial part of the Nix onboarding experience.
References:
There is no obvious way for beginners to learn using Nix most effectively. There are too many different, contradictory, partially outdated resources all over the internet. First-time users quickly get disoriented and confused. Even after months of continuous discovery, many still feel like beginners.
Design a learning journey ranging from the first encounter with Nix to mastering the skills needed to leverage common use cases.
As a minimum viable product, build a curriculum and associated lesson plans, oriented around user needs and according to best practices. As stretch goals, implement particular lessons identified as the most impactful to new users.
-
Develop a curriculum draft
-
Collect inputs
- Distill problems with existing approaches revealed by 2022 usability studies
- Documentation team's vision statement
- Evaluate and expand preliminary documentation survey
- Experience reports from teaching Nix
-
Identify learning objectives
- high-level (example: create a development environment with Nix)
- mid-level (example: use Nixpkgs to package your JavaScript project)
- low-level (example: find a specific version of a package in Nixpkgs history)
-
Develop a draft for a learning journey
-
Validate the draft with Nix experts
-
Make the resulting outline immediately visible for beginners at well-known touchpoints.
-
-
Categorise existing documentation materials into the Diátaxis framework, and arrange them in a meaningful order emerging from the curriculum.
- Create detailed GitHub issue descriptions where we encounter gaps, and use them as placeholders (also to measure demand)
-
Break down tasks for the writing phase
- Inspiration can be taken from our contribution guidelines
-
Prepare a contributor workflow
- Revise tutorial template
- Validate contribution guidelines with new contributors
-
Link or migrate existing documentation into a central location, as far as possible.
- There are some constraints due to incompatible licenses
-
Prepare and publish a call for contributors for the writing phase
Out of scope for this project:
- Writing tutorials or guides
- Improvements to the technical infrastructure related to documentation
If time and motivation allows, test run the contribution workflow:
- Pick a topic in the learning journey, for example one particular tutorial, which is identified as most impactful for beginners
- Audit and update or rewrite reference documentation it will be based on
- Write a tutorial or guide on that topic
- Leverage previously collected (third-party) materials as much as possible
Depending on available capacity, the group may create one or multiple articles. Authors will consult with the domain experts on a regular basis.
At the end of the writing phase we will run another round of usability studies concerning the orientation phase of onboarding, and compare with existing results. Specifically, we will evaluate, based on a set of pre-determined tasks:
- In how far beginners understand the purpose of and follow the proposed curriculum
- How well beginners are able to address their questions using the available materials
We will also inspect community metrics before the beginning and after the end of the project in order to estimate the change in adoption of certain skills. Specifically, these metrics may include:
- Number of questions and answers in the Discourse Help Category on the relevant topics
- GitHub issues and pull requests concerning the documentation
- Of particular interest are contributions to fill the gaps left in the curriculum by missing materials
- We expect this to indicate interaction with the new and updated materials
- Social media echo and anecdotal evidence
These metrics are so noisy that they have to be considered purely qualitative and best-effort. They can be expected to be strongly influenced by accompanied communication by the Nix marketing team, depending on that team's capacity. The experience with last year's development of the Nix language tutorial may serve as a frame of reference.
Our main budgeting consideration is that the financial support should enable work that would otherwise be impossible.
We consider the greatest leverage of a funded project to be the increased visibility into activities around documentation and the organisational learning we expect to happen in the process. Additionally, we see our diverse community as our greatest collective asset. A setup that enables beginners to grow into proficient contributors, domain experts sharing their experience with the whole community, and engaged volunteers taking first steps into the professional world – to us this promises the greatest long-term payoff.
Since creating documentation is much less "writing things down" and much more "building and disseminating knowledge", we decided to focus on paid support by domain experts, who shall guide activities, mentor contributors and share knowledge, and supervise progress. With a symbolic compensation we intend to encourage those contributors who otherwise would not step up to participate to take the opportunity for learning Nix and developing their technical writing skills, while creating lasting value for all users of the Nix ecosystem. We also want to incentivise community volunteers to provide documentation-specific technical support to contributors.
The NixOS Foundation and the Nix documentation team are committed to make the project happen. If we are awarded the grant, we have backing to close a funding gap of up to $5000.
| Budget item | Amount | Running total | Notes |
|---|---|---|---|
| Editorial lead | 12000 USD | 12000 USD | |
| Nix expert | 6000 USD | 18000 USD | |
| 6 contributors | 3000 USD | 21000 USD | 500 USD each |
| 2 volunteers | 1000 USD | 22000 USD | 500 USD each |
| total | 22000 USD |
The amounts will be adjusted according to the Google Summer of Code Purchasing Power Parity table, depending on the country of origin of applicants.
We plan for four project phases, each taking roughly a month.
| Time | Phase |
|---|---|
| 2023-05 | Planning |
| 2023-06 | Implementation |
| 2023-07 | Evaluation |
The planning phase will begin with a briefing and orientation period for everyone to get acquainted with each other and the situation. This phase involves review of the materials prepared by the documentation team, preliminary research, and creation of a refined project plan.
The refined project plan is to be comprised of
- Task breakdowns and assigments
- Timeline with weekly granularity
- Weekly schedules
- An evaluation strategy
for the remaining phases.
Implement the project according to the detailed plan based on the proposed scope.
The evaluation phase is for measuring project success, reflecting on what has been done, compiling a final report, and debriefing.
Depending on work load and contributor availability, this may be the time to reach for the stretch goal and fill one or more lesson plans with life.
In this section we outline each role's responsibilities and estimates on the time commitment required to fulfill them. These estimates are based on the experience of running the Summer of Nix 2022 program.
The editorial lead will take responsibility for the overall project and its success. The role's focus is to facilitate or carry out all activities necessary to reach the project's objectives.
Expected are a qualification or a track record in didactics, strong written and verbal communication skills in English, as well as experience in project management. A technical background is a strong plus.
| Phase | Estimated effort |
|---|---|
| Planning | 20h/w |
| Implemenation | 20h/w |
| Evaluation | 20h/w |
Total estimated effort: 240h
An expert Nix contributor will be available for answering technical questions concerning Nix specifics to everyone involved. The main concern is guiding the curriculum design, and introducing participants to the Nix ecosystem's particularities. We can expect issues to emerge in the process, and the Nix expert will be responsible for addressing them within the project's timeline as far as possible.
| Phase | Estimated effort |
|---|---|
| Planning | 10h/w |
| Implemenation | 15h/w |
| Evaluation | 5h/w |
Total estimated effort: 120h
Authors mainly take the role of learners with the responsibility to structure, make use of, and, first and foremost, write down their insights. They are assisted by the domain experts to reach a high standard of quality with their work.
Proficiency in written communication in English, and basic experience with Markdown as well as Git version control is required.
| Phase | Estimated effort |
|---|---|
| Planning | 5h/w |
| Implemenation | 10h/w |
| Evaluation | 5h/w |
Total estimated effort: 80h
The purpose of this role is to have someone available to support contributors when they encounter technical problems with the development process. This is likely to happen when the level of technical proficiency of participants varies due to their diverse backgrounds.
Total estimated effort: variable
@fricklerhandwerk (Tweag) is the organisation admistrator for this project.
He founded the Nix documentation team, and during and after Summer of Nix 2022
- ran a set of usability studies
- led the development of a Nix language tutorial
- mentored and supported documentation contributors
Currently he contributes to the Nix reference manual as a maintainer, and supports the Nix documentation team in its activities.
This project proposal was developed collaboratively by the Nix documentation team.
- We have evidence for the current problems in the usability studies (and countless anecdotes)
- Project scope is clearly defined by common use cases
- Guidance by experts will disseminate knowledge and skills in the community
- This will immediately benefit both users and contributors
- Setting good examples will impact the quality of future work
- Having a predetermined structure for contributions will accelerate developing the body of documentation
- Immediate user value by enabling quicker orientation and onboarding
If you have questions, please contact the Nix documentation team.
If you have suggestions, please open a pull request to change this file.