Aux has excellent ideas, and we want people to understand them. People have struggled with learning Nix, so we’d love to have an extensive set of docs and guides to refer to when you get stuck!
We think it’s important for documentation to be a focus from the outset. We’d like to look at what worked for Nix and what didn’t; work closely with other teams, particularly where those teams have user-facing concerns, and make some documentation that is understandable no matter your experience level.
To that end, we’d like to hear from everyone who has an interest in documentation. We need people who understand Nix to explain stuff, and people who are newer (or just haven’t understood anything!) to help us explain better.
Reason: (why do you want to be a documentation maintainer for Aux?)
Experience: (examples of past experience, both writing text and using Nix)
Thank you so much for starting this discussion. I was literally going to do it if nobody else did it.
One of my biggest pet peeves with nix was the lack of approachable documentation.
I work in technical education, so I’m down to write some documentation and make some tutorials.
This is an incredibly important topic and I think if we wish to draw inspiration from anywhere we should observe the archwiki, they have incredible documentation.
Reason: One of my top 3 gripes with Nix is mid docs. I would gladly help in improving it and making it more approachable.
Experience: I don’t have much experience in documentation but I know what I wish was documented when I started learning nix 5 months ago. I am comfortably daily driving NixOS but with plenty to learn in the Nix ecosystem so I believe I can be valuable in providing fresh eyes to the docs.
I’m absolutely down to help with docs. I haven’t written docs for Nix specifically, but I’m a technical writer who’s been in the field since 2014. I’ve made docs, tutorials, whitepapers, webinars, you name it, mostly for tech and software companies.
Reason: I think good documentation is really important, and bad documentation makes me extremely frustrated.
Experience: I’m a master’s student in Philosophy, so I’ve been writing to explain complex topics for years. I have been using nix for about a year now, and I think I have a good grasp of the basics. If there are topics I can’t write myself, I would definitely be able to help with editing for clarity etc.
I would love to volunteer as a doc maintainer! I love writing docs, and I found the nix documentation super limiting and fragmented. I like writing personal essays, but I also think I have a knack for simplifying big concepts so people can get the gist, for people like me who are engineer-brained and just want to do instead of completely understand its intricacies.
I also would live to join the documentation efforts. I think especially the entry docs and such are way too complicated and thats why the barrier to entry on nix is so high right now.
In the past I’ve been teaching quite a bunch of commercial Tech courses and over time got pretty good at explaining and understanding how knowledge is structured and how the concepts we stack on top of each other make or break the understanding of the reader/ learner.
Would love for aux to have a different learning curve and approachability
Reason: I want to help with documentation so newcomers have an easier time learning. Also, I want to ensure all documentation is centralized on one “general” platform rather than spread across many inaccessible/hard to find places.
Experience: I’ve helped with documentation on the Space Station 14 project in the past. I’ve also helped a couple people with learning Nix/NixOS in the past
I’ve been using Nix for a year or so and I’m comfortable administering my own computers and some small devexp stuff, but I still feel pretty fresh to the scene. I’d be coming at things from more of a beginner’s perspective, but I’m happy to test drive/provide feedback on/be a guinea pig for new docs however I can!
I’m a current student journalist (4 yrs of experience) and I’m great at editing things down without making them lose their substance. I’m good at simplifying and explaining technical writing as well, and so I’d like to help make these docs more approachable.
While I have no experience writing docs, I would love to give feedback and help improve the documentation in any way I can.
Reason: Learning Nix and about NixOS these last few months has been a huge task. The documentation is so disjointed and missing critical information (about flakes especially), helping people get into Aux a lot easier would be a dream come true!
Experience: I have been learning Nix and NixOS configuration management these last few months. I manage my own NixOS server and Laptop configurations.
I pretty interested with helping with docs. I don’t have a lot of experience (I’ve mostly done some edits on the postmarketos wiki) but I want to especially help with adding troubleshooting sections and notes for common problems whoch is something the nix wiki was very lacking.
I’ve not had a lot of nix experience but for the aformetioned issues and general confusion, so I can also help giving feedback on documentation for newcomers
Quality, up-to-date documentation is absolutely essential for onboarding new users and contributors, as well as for fostering a healthy, supportive community.
My experience with Nix and Linux in general is from a userland perspective, which is to say that I am not a programmer and do not use Nix for development, but I understand the technology at a surface level and have been using it exclusively on my personal computer for a few years now.
For this reason I am not qualified to contribute much new documentation, but I’d be happy to help review docs for how much clarity they provide to less technically-inclined users in order to soften the learning curve.
Reason: I believe documentation to be a vital part of making software (ecosystems) as large as Aux succeed (in the sense that lacking documentation does not become a reason for disregarding Aux as a viable choice). I also want to take this as an opportunity for me, to get better at explaining (technical) stuff.
Experience: I haven’t really written documentation for nix so far, but I’m,a nix user for almost 3 years now. Text writing wise, I have no background in creating technical documentation, though I’ve written reference documents, tutorials here & there (mostly private, unfortunately, but an example can be found here).
Reason: Any product is only as strong as its documentation. It can be the salvation to the problem of humanity and still have zero impact if nobody knows about it. I am very enthusiastic about nix and deeply invested in the technology for personal & professional use.
Experience: 20 years of professional software development, automated testing, documentation, teaching, and conference organising. Anything from solo spare time projects to massive industry-leading products, from quick screen recording walkthroughs to one-week on-site crash course designs, full-team-barrage deep-dives, and speaking in 10-20 different cities worldwide for audiences of all sizes and diverse backgrounds.
I don’t have a ton of spare time next to family and small business, but I would love to assist where I can.
Reason: Lack of good documentation has been my biggest gripe while migrating to NixOS, I have long been critical of Nixpkgs documentation, and been making efforts to improve it behind the scenes.
Experience: I have not contributed direct documentation to Nix, however, I have formal training in writing instructive papers as a part of my major (+post-grad education), and I have been quite strict on documentation in my personal projects. My experience, although short, is quite vast in terms of the scope of the projects I have contributed to. I also co-maintain ndg, a tool for documenting Nix related projects with ease with this goal in mind.
for joining the documentation effort.