There’s a lot of available open source software for documentation. I’m wondering what we want to use. Something like mdBook (this is what the rust book uses), something like readthedocs, or perhaps wiki software like mediawiki / wikiJs?
I personally have some experience with mediawiki and I think it lends itself well towards the aux use case by comparison to something like mdbook which feels more like its designed for tutorials.
6 Likes
I’ve used docusaurus for some things before. It’s been pretty nice to work with in my experience. 
That being said though, mdbook is definitely a solid choice.
3 Likes
Also, if we’re going to build a wiki a la the Arch wiki, we’d definitely need something like mediawiki or wikijs as mentioned in the OP.
4 Likes
Something I’ve been thinking about for a while is using MDN’s tech to create our own documentation center. That would make it a bit easier to have a lot of different parts of the ecosystem all documented in one place with cross-references.
5 Likes
So, a while ago, I wrote some developer documentation for the fedoraproject over at the fedora developer portal, they seem to use Jekyll for their stuff. It was pretty easy to contribute to it.
2 Likes
It would be SO good to have a wiki up and running straight away. The Arch Wiki is one of the greatest things in the whole of computing IMO. The NixOS wiki went wrong because people didn’t take it seriously enough. (Which BTW is nobody’s fault, as far as I can see - in the crucial early stages it just fell between the cracks.)
3 Likes
I’d be happy to help moderate a wiki, in case that helps.
1 Like
I like the wiki approach for ease of use, but I’d probably lean more towards something Markdown-based like Docusaurus. As long as it makes it easy to manage, cross-link, and propose changes.
3 Likes
I would like to add to my previous comment about software that we use that I’ve done quite a bit of research for this when creating catppuccin’ CAT-0004-Wiki rfc. And I think this is a good resource to read over for everyone who is curious what options we have and some use cases out there for each software.
3 Likes
If we choose to do a Wiki for all the project-related documentation, I can’t recommend DokuWiki enough. Compared to MediaWiki, it makes use of namespaces for structuring the Wiki-pages and also has built-in ACLs. Furthermore - with the help of some plugins - one also gets templates, structured data and automatic table creation from this structured data.
It’s really powerful and I think especially the built-in namespaces and ACLs would be really nice, since these would allow for having more restricted sections, where e.g. only members of certain SIGs and Working Groups can edit pages.
3 Likes
On a slight tangent, I think it’d be a good idea to have an “Aux Book” in the same way that rust has the “Rust Book” that we can point people to as the first steps to working with aux.
So, we’d have an Aux Book which is basically a tutorial, and then a dedicated Aux wiki that would actually document things the way the Arch wiki would.
10 Likes
Introduction to Flakes | NixOS & Flakes Book, something similar to this perhaps? Maybe it would be worthwhile to contact the author and see if they’re down to help with Aux.
12 Likes
That’s exactly what I had in mind when I pitched that idea, yeah 
2 Likes
I’ve taken a look at docusaurus (I didn’t know what it was but now that I do it feel like I know about 1000 websites that use it). I’ve come to the conclusion docusaurus would be really good for a general wiki. However I think something more “one topic per page” like mdBook is better for a tutorial.
3 Likes
I think this is a good idea as long as both clearly reference each other.
One problem I’ve seen newcomers face is that they don’t know where to look for documentation and general info, so keeping things mostly centralized would help a lot and lower the barriers to entry significantly
3 Likes
A very similar assessment to @Axel and my own comments. If i had to give a winning idea right now. I think I would say a mdbook for basic into into using aux and then a fully fledged mediawiki that really gets into the nitty gritty.
EDIT: though having read @vera comments I can’t say this will be a flawless outcome.
3 Likes
Yea something on each front page that clearly says “hey this is for ‘a’ group, if you’re a part of ‘b’ group, look here”
2 Likes
I just want to point out that while I don’t really have much say in what software we should use because I don’t have a lot of experience with hosting different types of wiki software, I think that considerable time should be spent on how it looks. We want it to be as accessible as possible for newcomers, and I think that requires it to have a modern looking UI. I think GNU Guix Reference Manual is a good example of what we should avoid – as someone who looked into Guix a little, this was an awful experience. There is little contrast between block code and normal text, inline code and normal text looks very similar, the buttons to navigate between sections is very small, and it doesn’t leverage design elements to guide users to things the manual wants to emphasize – it’s all given the same priority (visually speaking). This led me to a lot of time-wasting reading through the entire thing instead of skimming and finding what I need quickly, which would have scared me off if I didn’t already come into it highly motivated to learn. I think that the theming capabilities of the software should also be heavily considered, and that having a set colorscheme in mind while setting it up should be one of the higher priorities.
1 Like
or even just “This book is about the concepts and fundamentals and doesn’t contain implementation details you may need when actually using this software to build new projects” and “While this wiki makes a best effort to be user-friendly, you’ll have an easier time reading The Book first and understanding the concepts if you aren’t already familiar.”
obviously that can be shortened and simplified, but as a non-novice dev even i have to look at starting docs once in a while.
1 Like