I like your ideas paper - particularly the information architecture approach. I would add that there should be aspects of “explain how things work and why they were designed a particular way” in tutorials and how-tos - not to get in the way, but to provide extra information (and pathways into other sources). I find it necessary sometimes to just “copy and paste” something because I don’t understand how it works, which can lead to more issues later. Those hooks would at least provide education and perhaps better questions when users get stuck.
I’ll try and take a deeper look later…
Thx @figsoda for mentioning my projects here.
I do generally agree to @zmitchell s points. From my perspective it would be nice to have a documentation feature built-in to nix. Like in rust. → Documentation - Rust By Example
Thats why i created the nix-types project. It aims at using and unifying the current doc-comments.
Which are then used by noogle to automatically generate documentation.
Having only doc-comments is necessary for functions and other parts of nixpkgs because nobody can really track every single function and its better to have the documentation for them right where they are declared.
However it is needed to have more documentation like “intro” “how to build sth” etc…
This is also part of my current type project but I didn’t yet started implementation on that extension.
The nix-types project is gone really well so far. I have a parser capable of parsing the doc-comments, including creating AST from type-annotations there, which could be rendered into some markdown tables.
I have the slight feeling that the RFC about “rewriting the docs” has stalled out somehow and there is not so much happening (correct me if i am wrong)
In the end i’ll try to build a Documentation system that reads:
- Doc-strings (Description, Example, Type)
1.1 Provide Syntax Highlighting and Feedback for wrong syntax in those comments. - External Markdown files for Abstract explanations like “How to build sth” etc.
If the “nix-documentation team” sees overlapping points here i’d be very happy to discuss collaborations.