Documentation improvements

I think the explanation for how propagation works is too detailed for a user manual. I think the first thing in that section should really just be a couple examples of when propagatedBuildInputs is needed and not needed. I think the detailed explanation of exactly how dependencies are propagated and in what way should be saved for a different document. Maybe a wiki page?

I do not think that the Nixpkgs manual is a user manual; for a long time it was called Nixpkgs development manual, but it also has accumulated some user-oriented notes that had no better place to go.

And of course there are notes for maintainers of normal packages there, and there are things for people who debug core parts (e.g. when wanting to fix cross-compilation to minor platforms), and these are also not always well-separated.

But this approach takes the problem out of the papercut scope, I guess…

The manual structure has been bothering me for a long time as well. For starters, the separation between Nix, NixOS, and nixpkgs - normal users don’t care about which part a given thing technically belongs to, they just want to know how to do a thing.

We should probably have a different documentation division: something like user manual, development manual, internals reference. Each manual could then, for example, have highlighted/marked sections with “this section only applies on NixOS” or “this section only applies of you’re using nixpkgs”, and so on.

Anyhow, this does veer off into more detailed discussion :slight_smile: We should probably have a dedicated thread for this? Not sure if Discourse has a ‘split thread’ feature, to move out these two posts and link to the new thread.

cc @ryantm

7 Likes

We had this discussion many times, while most agree, there’s no plan how to plan the seed to actually start moving in that direction.

1 Like

Is it a technical problem (eg. “what stuff can we use that supports highlighted sections like this”) or rather an organizational problem (eg. “this is a big job, where do we start without breaking the manuals for users or going out of sync”)?

Also, are there any existing issue threads or such that contain the previous discussion(s)? I haven’t run across them.

Most of these were offline at nixcon and such, it started with first Nix gatherings 2014 when I invited Mikey Ariel (one of the organizers of WriteTheDocs conference).

The gist is that docbook is for writing books, if you want to scatter documentation around in different formats it’s actually a lot of work since tooling is decades old.

Not to mention for SEO you want each documentation section to be separate page, as Google doesn’t like huge dumps of text as it’s a SEO trick. Once you have multi-page docs, you need search…

So there’s a deadlock: docbook is what we have and it seems to be semantically superior, while there’s little effort to write the tooling to write such structured documentation.

I’ve been strong proponent of asciidoc (which actually translates to docbook) and https://asciidoctor.org/, we’ll actually be releading a tool for documentation of NixOS projects soon backed by this tooling.

As for Nix community I think as always, someone enthusiastic should take the lead and I highly doubt anyone will be against better docs :slight_smile:

3 Likes

Also these things are very well known in documentation circles

2 Likes

Looking through the AsciiDoctor documentation, I can’t find any way to define marked “this only applies to NixOS” sections. All the block types seem to be pre-defined and non-customizable. Am I missing something?

As for Nix community I think as always, someone enthusiastic should take the lead and I highly doubt anyone will be against better docs :slight_smile:

You shouldn’t underestimate the difference in people’s ideas of «better», though.

Could you explain better what’s your objective? You can do imports, so that way you can organize and reuse snippets of documentation. There are also tags, so you can say asciidoc --tags foo and it will conditionally include or exclude per tag.

There are admonition blocks, but are styled a bit differently in default theme.

Those are only available in a fixed set of varieties though, if I understand correctly?

Some months ago In my spare time I’ve built an automatic converter from docbook to Sphinx ReSt format, It is almost complete, but it lacks support for other document inclusion and the annotated source examples, unfortunately sphinx has no support for those. If it can be of any help, I can resurrect it

I also did that experiment back in 2014: https://static.domenkozar.com/nixpkgs-manual-sphinx-exp/

but unless there’s decision to convert everything, it’s all in vain :slight_smile:

1 Like

You can define text and pick your icon. And category would be “INFO” I suppose.

What would that look like in asciidoc syntax, though? As I understand it, it would require re-specifying the icon and text for every single such block, which is not practical.

What I’m looking for is some sort of way to have reusable wrapper elements, similar to what MDX can do. So that you can simply mark something as “this is NixOS-only”, and the actual markup (what informational text to show, what formatting to use, etc.) is handled elsewhere in a consistent manner.

(Also, @ryantm, thanks for the topic split :slight_smile: )

(Thanks for posting this! Now I have a way to remember how to find it. :P)

My first idea was: Why not use Markdown? Everyone can use it!
But after checking out AsciiDoc, there are good reasons to use that over Markdown for documentation.

https://asciidoctor.org/docs/asciidoc-vs-markdown/

There is also a documentation platform called Antora for usage with AsciiDoc.

Even the default theme looks more professional and usable than our curent documentation!

So i support the migration of our documentation to AsciiDoc!

A plan could be:

  1. just convert everything to AsciiDoc, convert to DocBook again in build and use current setup
  2. research a good tool to create HTML with great UX and implement that for the build process

Then we can start to organize the information better. But that’s a different topic.

An easier to use Markup would help to get more people involved in documentation and that is very important for our project!

2 Likes

What’s the status of this?

Half way done at https://github.com/hercules-ci/docs.hercules-ci.com/, then we need to generalize it (for any Nix project).

2 Likes