Documentation office hours, onboarding for new maintainers

Dear all,

I’ve been working on improving documentation in the Nix ecosystem in the past two years.

Members of the Nix maintainer team recently took on the challenge to onboard one new team member each in the next 6 months. If you want to take charge of Nix reference documentation, I offer to get you on the path to merge access to Nix and code ownership of the Nix manual or any other piece of documentation in the Nix ecosystem.

For that purpuse, I will offer approximately one office hour each day from Monday to Friday for the next few months. You’re invited to join me to triage, review, and write issues and pull requests concerning Nix documentation – and of course to learn to know (from and with) each other. I’ll try to distribute the hours across the day to make it more accessible, but prefer 7:00-11:00 UTC. Expect the times to converge on helping whoever shows up consistently. I will also shift events according to my availability.

Check the NixOS calendar for Documentation office hours.
Send me a message on Discourse or Matrix with your e-mail address to get an invite and receive reminders.

I hope to create a routine for myself as a side effect, in order make more predictable progress on issues that have stalled for too long because other priorites took away attention. Doing these things together is a lot more fun.

I’d expect future committers to ask their way through problems they cannot solve alone, clean up their own mistakes, and keep promises or be up-front if that’s not possible. I’m open to take as much time as needed to answer questions or try things out.

Some context: The contention about granting merge access in the past was not about qualification – we know there are highly capable developers that already do great work to improve Nix – but about building a trustful working relationship. As far as I can tell, this is how much of the community, and the Nix maintainer team in particular came together. But we struggled to expand the team since it has been founded.

Experience with community teams has consistently shown that repeated synchronous collaboration is be the most effective method to build trust, create alignment, and pass on tacit knowledge that may never get written down. I hope this little challenge will contribute to systematically reducing the friction we’ve all been experiencing with the Nix ecosystem.

This effort is sponsored by Antithesis :sparkles:.

19 Likes

It’s been 6 weeks of office hours, and we got a couple of very interesting sessions out of it, with great discussions and a number of merged pull requests. Unfortunately I have to stop it here, both because the funding ended and to make room to focus on other things. Thanks everyone who attended and grabbed a shovel, and great many thanks to Antithesis and Tweag for making this possible!

Regular, fixed times were great for consistent progress. And it seems that a few people enjoyed the predictable opportunity to meet.

I’ll still do some volunteering and respond to pings, help get PRs merged when asked, and you can reach me in the Nix Documentation Matrix room or here on Discourse, also to hang out Jitsi Meet every once in a while. But likely I won’t focus on moving forward anything specific until further notice.

Feel free to get in touch if you want to chat or get things done together.

8 Likes