NixOS- code vs wiki vs manual

Hello, Does it bother somebody else that NixOS has multiple sources of truth? The code is very public on github. Then there is the nixpkgs path in the /nix/store. Both are a few key presses away. Then there is the manual which is somewhat hard to edit because of it’s xml. (I’ve made a couple of changes but the recent one kind of added a mental barrier for me). Then the wiki.

I know that code is necessary (duh!) but between manual and wiki, while manual adds a professional touch, I think that the effort is duplicated and in the case of manual somewhat wasteful.

I just want to start a discussion about this and ask people what they think- I think a good way forward could be eliminating one and using a simple format for whichever survives.

I personally recommend NixOS for enterprises and as such a manual is a basic decency. So how would it work if the wiki were eliminated, manual format was simpler and there was a separate triaging for doc related PRs. (while still keeping it in the monorepo, hence synced with code at all times by default)

2 Likes

I’ve been thinking about this as well. The wiki is unlikely to be eliminated because it is (and is probably better off being) community run, so shutting it down would require a weird ‘no making wiki for NixOS’ policy.

Also I think it’s valuable to have information in the wiki form. If anything, it’s much easier to add stuff to a wiki, and it’s also in a more topic-oriented, bite-sized form.

The above is from a ‘small’ user perspective. I don’t know about enterprises’ needs but I’m almost certain that eliminating the wiki and just having a manual is not the way to go.

1 Like

Maybe going the way of the Arch Wiki would be a good idea?

Quoting from there: ArchWiki is maintained by the official Maintenance Team and thousands of contributors.

It is widely considered to be quite good. Although, I wouldn’t know if that is an acceptable format for the enterprise.

Btw, are there some devs/maintainers who we could/should talk about this?

1 Like

Couldn’t you have a “best of both worlds scenario” where the content for the manual was pulled and assembled from a section of the Wiki ? That way you could continue to have both formats but they wouldn’t get out of sink.

That being said, how big of an issue is this? It seems like having a normal documentation and a wiki is fairly common among Linux distros.

That would be pretty great. If doable:)

Having dug a bit deeper into the wiki I think we dearly need more people working on it
See: WantedPages :sweat_smile:

Side note: link from NixOS Wiki:Contributing - NixOS Wiki on thinking behind wiki structure - Types of Documentation

This thread is a bit funny to me because of historical context. We actually started out with an official wiki (well at least that was the status when I got started), then slowly moved to a manual format. I think we did that move because of malicious edits or something. Then somebody resurrected the wiki as a community project because some people like the wiki format better.

So now we’re discussing abandoning the manual for the wiki (or the other way around).

2 Likes

I think I personally prefer the wiki format of which the manual could be a/the main article. One advantage of the manual approach is that the code and the documentation live together though.

IMVHO, from an user point of view wiki and manual are different things.

The manual is useful for new users, when I’m started trying NixOS I
(skim) read the manual just after I download the iso.

The wiki is useful for specific topic. Like “how to configure zfs
crypto?”, “how to configure brother printers?” etc. It’s also a good
place for noting small potential annoyances, for instance when I
upgrade from 19.03 to 19.09 stable I get a

error: stack overflow (possible infinite recursion)

and quickly found (via web search) that’s an ulimit issue, solved
with

ulimit -s 100000

Another issue I encountered time ago was Anydesk that fails to
download from official mirror, but I was able to download manually,
I quickly discover

nix-store --add-fixed sha256 file

And many other small things like that. Having them in a wiki, easy
to contribute by any NixOS user, it can be far better than have to
search the web for any issue… Google is a damn good search engine
of course, but…

IMVHO things like Emacs/GNU Info pages, with proper content, as
locally available docs in any NixOS install, at least easy to
install like any derivation would be a very nice thing especially
if the manual advertise it quickly like:

  • if you look for a package: info nixos, ‘m’, package,
    press ‘i’ to search one, dear packager please add notes
    to the relevant docs section so people can easily read
    about it…

  • if you look for an option: info nixos, ‘m’, options,
    press ‘i’ to look for a specific one.

  • if you look for an error message …

etc. Having something local, that can also push something back so
for instance “registered” users, from their NixOS instance, can
write down something and push to that “wiki”, can be a real
gamechange in docs term. Of course GNU Info is not ideal especially
due to texinfo, but consider a thing:

  • man pages, very little used, a doc. system

  • info pages, another very little used doc system

  • on-line wiki

  • manual

  • discourse

  • GitHub …

most of these overlap, at least partially, and none of them are
really useful due to it’s content, accessibility, readability,
popularity etc. As an Emacs user for instance I found info a
very good UI to read docs, unfortunately lacking complete and
good contents. I casually use manpages, normally for an option
I forgot, I almost never use apropos/man -k, I almost never use
wiki search, but sometimes I land to the wiki via Google search,
I’ve (skim) read the manual one or two in few years of nixos,
so developers time invested in it (thanks!) for me was useful but
only in a very limited occasions etc.

Nearly all agree that docs are important, in any software project
and in general, nearly no one seriously discuss about documents
these days, and most documentation systems as a result are in a
really sorry state or by themselves technically or because of
their contents… Nearly all on-line approach fails: ReadTheDocs,
SlideShare, … are still there, but after an initial bubble they
fade. A local thing, always there, quickly available, well
advertised, easy to use and contribute can IMO succeed…

Sorry for the length and poor English. I’m write via mail so I hope
that discourse render properly the message.

– Ingmar

1 Like

I think the manual is good because it’s largely a “concise” look at certain parts of Nix, where as the wiki is much more in-depth on a particular topic

2 Likes

The complete lore can be found on NixOS Wiki:History - NixOS Wiki which is one if the articles which do not fit in the official manuals but only into a wiki context.

1 Like

I feel like it’s a hurdle to little bits of contribution from casual users, and thus a hurdle to random but useful bits of content. Not saying that we should get rid of the manual, but thinking of the wiki of a public cache of connected knowledge, I don’t think of it, say, getting out of date would outweight its benefits. If there’s official maintenence then great, but if there isn’t, the wiki can still be a fantastic place for users to learn stuff that’s not on the official manuals or maybe stuff not so extensively described on the manuals.

1 Like

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)? A downloadable wiki like the GitHub ones? Something that’s both organized into options/packages/… and also publicly editable?

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. Or maybe you consider it not being ‘a local thing’ a very important missing bit, in which case I’ll go back to: Is a downloadable wiki what you want?

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:

  • a small intro

  • a series of specific topic like “kind of installation” with a quick
    index like

  • LUKS+LVM on EFI system

  • ZFS root

  • mdraid setups

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

The reason why I brought this topic up is because some of the things I was looking at when I was new were inconsistent between wiki and manual (android dev for one?) ,something a versioned manual handles better…

1 Like