Hi,
I’m not sure what you mean. Do you want something that’s basically
both a manual and a wiki (I don’t see how that work)?
Not in the documentation sense. I mean NixOS live iso have nixos-help,
the manual, in html, rendered via w3m. It’s useful, but limited. If I’m
in the process of first installing NixOS a small howto is better, so a
different kind of nixos-help. A system command that run something like
GNU Info instead of w3m, where I can read:
…
Something quick and easy to navigate, like GNU Info. Something one can
use aside, locally, in the NixOS live CD, from both CLI and GUI.
If I’m evaluating NixOS up front like: I’m interested in NixOS? Does it
help me? Does it fit my needs? How much I have to learn? In that case a
simple “at a glance intro” on a website with at the end: “for more here
the basic user manual, pdf, xxxpages”, “programmers manual, pdf,
yyypages”, “intermediate user manual”… is a VERY nice docs, I can
decide in a minute if is interest or not, and if yes I can go deep a
step at a time, for instance quickly looking the pdf and if decide that’s
useful for me print it and read it with calm.
After installing NixOS, using it, I’d like to easily explore packages
and options, again locally on my system non via web so have a local
UI like
When I have a specific problem a wiki is a good place to look for a
solution OR to write down one when I found by myself.
Documentation is not about “a thing to be written” but a “workflow to
accompany the reader in he’s/she’s ‘Nix{,OS}’ life”. It must be easy
and available when needed, as needed, easy to read, quick.
That’s a thing MOST people today’s ignore. All say “RTFM” but no one
really care the FM itself. The result is a tons of different an partial
system that are simply not effective/in a semi-abandoned state from the
start. That’s I mean.
Contribution point is the same: an official manual should be curated so
casual contribution can be treated like patches and approved by some
trusted project contributor, who also know Nix* world enough to judge
the content.
Wiki contribution must be kept a bit “supervised”, but should be super
easy to made, and a local installed app that talk to a remote system
is a nice way to get both: a local Nix* user simply fire up the app and
start typing. A non-Nix* user who want to create a mess need to port
the app or use NixOS to made it’s mess. Of course it’s not a real
guarantee but it’s a nice step toward a guarantee IMVHO.
That’s is. Docs must be integrated, not an on-line service somewhere in
the world. It must be accessed like Emacs docs, immediately and simply.
If I do not know what and Emacs function can do I simply type C-h f or
C-h v is it’s a variable, I can consult the changelog with C-h n etc,
anything is at my fingertips. It’s not “an ancillary documentation I
can consult”, it’s part of the day-to-day workflow. Nix* does not have
the Emacs power but can have a simple docs mediated by a simple UI.
I also don’t understand this. I don’t really use SlideShare so I can’t
comment on that, but I don’t know why you consider ReadTheDocs a
failure, as I use documentation based on it quite often and I consider
it a nice solution.
It’s nice if you want an article, it’s definitively not nice if you look
for help. StackOverflow is more common for help, but as any proprietary
platform is “in competition” with others, contents get duplicated,
efforts moderated etc. A built-in system does not have this limitation
and being part of the system itself is easy to maintain and use like any
other derivation.
My English it not that good and I’m not much succinct but try to re-read
the above scenario of a new or aspiring or normal user. Try to imaging
how docs can be used if they are available as described.
– Ingmar
