Hello everyone, and welcome also from my side to this year’s Summer of Nix.
My name is Valentin, and I will support you with improving Nix documentation. Documentation and the steep learning curve have always been a sore point in the Nix community. We will change some of that to the better in the following weeks.
Your work is immediately valuable
I think, what we are going to do this year is very important. It will have an immense impact on both the Nix community as well as the software industry in general. There are already at least 2,000 active community members, more than 4,000 verified Nix users, and we estimate the global user base in the tens of thousands.
Nix, Nixpkgs, and NixOS already are working products, and for good reason many of their users love them so much that they do not want to go back to a world without them.
But for many years now we hear complaints that Nix is too hard to learn. It is confusing, frustrating, and requires significant effort to get productive or solve more advanced problems. You will probably have experienced it yourself. Yet, everyone here stuck around. It seems we are convinced that the ideas behind it are so powerful that the effort was worth it.
Our goal here is nothing less than help bringing that power into the daily work of hundreds of thousands of software developers around the world. One way we will do this is by clearly communicating how to make to make use of it.
You have full support
Nix users unanimously ask for better documentation, as it is currently the main usability issue and barrier to adoption. The project founders and core developers strongly support your work, and made arrangements to accommodate it in a timely manner. The companies and institutions who back them invest their employees‘ time (like Tweag for me and @mat) to support our collective effort, as they are highly interested in establishing Nix in the software industry. The European Commission itself funds this project with 100,000€, as it recognizes its strategic importance to make the open source ecosystem more accessible, and foster democratic values for the public good, not only in the European Union but worldwide.
Literally everyone will benefit from more and better educated Nix users, more qualified contributors, and the improvements and additions that will ultimately follow.
We can do this, together
I firmly believe that is does not have to be hard to learn, to use, and to contribute to Nix. The concepts are simple. We just haven’t converged on the best way to teach them yet.
This is exactly what we will do, together.
First of all: We cannot really fail, as almost anything we do will be a noticeable improvement.
The most common use cases already work amazingly well, and we will further improve onboarding to be as fluent as possible. Some things are not polished yet, and require more explanation. We will collect, revise, and add material to make that happen. And there is a lot of work in progress in the technology, where we have no final answers yet, and we will help users find their own way by providing overviews and pointers.
Most probably none of us is an expert in teaching or technical writing – certainly I am not – and some of you are not even expert Nix users. This is fine. It will and must be a learning experience for everyone. I believe it is the only way: We can only get good results if we stay curious, if we expect not to know the answers in advance, and instead try find them by observing carefully and being diligent.
I have prepared some initial tasks to get you started working on documentation, a set of guides and best practices, and a structure to fit your work results into. All of this is based on observing many people trying to learn Nix using the available material, and seeing where they struggle or fail.
Let us continue observing – ourselves and each other. During your project you will hopefully learn many things. Write everything down. Note where you have difficulties. Give feedback to the authors, or even better: suggest improvements directly. Show to others what you have made and watch them interacting with it. That will clearly direct you on what to do next.
Your notes will help you keep track of you have learned and made, and they will be the basis for the reports you are supposed to write.
I promise you, you will be surprised how much we will accomplish together.
I will be on vacation until 2022-07-27. After that, you can ask me questions via direct message or email any time, and schedule calls within my office hours when necessary.
Please use public channels for communication as much as possible, such that others can help out with their expertise and everyone can make use of the answers. Comment on the relevant GitHub issues and pull requests, write on Discourse, and only resort to the internal Summer of Nix Discourse category or direct messages where suitable.
What to do next
Pick something you care about with the Nix package manager, the Nix package collection Nixpkgs, or NixOS. If you are not sure yet, take time to do some research and ask around. One or two days for finding something reasonable to work on should be fine, just take notes to keep track of what you are trying to figure out and why you think it is more important than anything else.
How to contribute to documentation is a set of guidelines and generic tasks the documentation team has identified to improve the overall situation, ordered from fairly simple to rather involved. I recommend taking any of the simple tasks and finishing something quickly to get a feeling for the pace.
You should be able to do all of that on your own. Trust your intuition and pick the most valuable thing you can actually accomplish in a day or two.
Try to avoid going down rabbit holes, and ask questions in public if you get stuck for more than two hours. Leaving work unfinished is fine as long as intermediate results are publicly visible, e.g. as an informed question on Discourse showing your work, a NixOS Wiki article, an elaborated GitHub issue or a pull request draft.
Your first report
Please prepare your first report by 2022-07-28, based on your daily notes, so we can synchronize in the first week of August.
Your notes should contain the things that you considered or learned, and the changes that you made to the various resources, with links for easy navigation. Please use bullet points, the report is just to provide an overview of what happened and should be quick to skim.
Example:
- learned from @garbas that GitHub - NixOS/nixos-homepage: Sources for nixos.org has a preview feature for pull requests
- only works for branches in the repository
- prepared tasks for Summer of Nix participants
Post your report as a reply to this thread.
Looking forward to talking to you soon. Have a great Summer of Nix!