In the long term, “more docs” can only be the intermediate work necessary to pave the way for “less docs” and “more intuition”.
It is clear that the well-known “TL;DR” has its roots in an educated observation about real humans.
The sheer volumen of documentation is becoming its biggest accessability obstacle.
There are many instances throughout the docs, where entire paragraphs or sections could be disintermediated at the hands of intuition.
Just one example: a “how-to” — not a concept — on style is usually a missed opportunity for automation. But there’s certainly a lot more candidate UX categories.
As said above, in my opinion, we have (currently) chosen a different, second best, focus on our approach.
Could you give one example? I’m not sure I understand what you’re trying to say here. Should the docs be more intuitive to navigate? Should explanations rely more on building intuition than documenting behavior in a structured way? Should we rely more on examples than explanations?
In fact, by “disintermediate documentation”, I refer to aproximately this diff:
- some paragraph about something
+
Now, how does that work, at all?
It requires a strategic and integrated view on documentation not accepting any premature constraints, such as taking e.g. the nixos/nix implementation as an invariant input variable to the documentation effort.
To the contrary, as the best documentation is the one not in need of being written, I’m arguing to shift focus (or a little less: complement perspective) of documentation and understand rather its requirements as the input invariant to how Nix is designed and refactored.
TL;DR
Documentation is also user centric development and UX prior to writing the first paragraph of prose.
Ok yes, that makes sense. I’m not super happy with your example, but the TL;DR explains quite well what you mean.
I’m personally working on improving the UX, but I don’t think this means the current effort of writing documentation is misplaced.
Well, part of it is invariant over a certain time-frame. Of course everything can change in 10-20 years, but the old CLI and the NixOS module system will mostly stay as they are within the next year or two. It’s much quicker to write new documentation for things that exist and people already use as opposed to not doing this. For experimental interfaces, we can of course break more and improve the usability quickly.
That sounds nice in theory, but even requirements are constantly changing as users find new ways to use (and abuse) Nix.
Absolutely, that’s a great reflection on the issue!
I’d reply that the (low) elasticity of invariants and ecosystem constraints that you mention are also a byproduct of the predominant mindset.
So at beginning of the causal chain lies the predominent mindset.
As holders of a defacto mandate from the end user, I think Documentation is a great force to include making transformative amendments to the predominant mindset part of their mission.
