# Nix journey part 1: My grand unified theory of Nix documentation
**URL:** https://discourse.nixos.org/t/nix-journey-part-1-my-grand-unified-theory-of-nix-documentation/26068
**Category:** Links
**Created:** [March 6, 2023, 7:26pm UTC](https://discourse.nixos.org/t/nix-journey-part-1-my-grand-unified-theory-of-nix-documentation/26068 "2023-03-06T19:26:10Z")
**Posts on this page:** 4
**Page:** 1
### Author:  [@zmitchell](https://discourse.nixos.org/u/zmitchell)
#### Post date: [March 6, 2023, 7:26pm UTC](https://discourse.nixos.org/t/nix-journey-part-1-my-grand-unified-theory-of-nix-documentation/26068/1 "2023-03-06T19:26:10Z")
> **[Nix journey part 1: My grand unified theory of Nix documentation](https://tinkering.xyz/nix-docs-unified-theory/)**
>
> Since the last post I've been in contact with some members of the Nix community with regards to joining the documentation team. From that discussion and my experience with other ecosystems I've had some ideas rolling around about what the ideal Nix...
---
### Author:  [@Damage](https://discourse.nixos.org/u/Damage)
#### Post date: [March 6, 2023, 9:43pm UTC](https://discourse.nixos.org/t/nix-journey-part-1-my-grand-unified-theory-of-nix-documentation/26068/2 "2023-03-06T21:43:57Z")
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…
---
### Author:  [@figsoda](https://discourse.nixos.org/u/figsoda)
#### Post date: [March 6, 2023, 9:57pm UTC](https://discourse.nixos.org/t/nix-journey-part-1-my-grand-unified-theory-of-nix-documentation/26068/3 "2023-03-06T21:57:50Z")
@hsjobeki for [noogle](https://noogle.dev/) and [nix-types](https://github.com/hsjobeki/nix-types)
---
### Author:  [@hsjobeki](https://discourse.nixos.org/u/hsjobeki)
#### Post date: [March 7, 2023, 8:49am UTC](https://discourse.nixos.org/t/nix-journey-part-1-my-grand-unified-theory-of-nix-documentation/26068/4 "2023-03-07T08:49:52Z")
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](https://doc.rust-lang.org/rust-by-example/meta/doc.html)
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:
1. Doc-strings (Description, Example, Type)
1.1 Provide Syntax Highlighting and Feedback for wrong syntax in those comments.
2. 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.