Giters

NixOS / nix.dev

Official documentation for getting things done with Nix.

Home Page:https://nix.dev

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Inconsistent styling and lack of cross project navigation in Nix documentation

lf- opened this issue · comments

commented

Observations

https://nix.dev/reference/nix-manual
and the nixpkgs and NixOS manuals and nix.dev don't have any navigation links between them or consistent styling.

related discussion https://logs.nixos.dev/room/!avYyleMexqjFHoqrME:nixos.org/?anchor=$1a-p0jIFGfppHqFadSnQIpoX40mUALH9qt7griX9qWk&offset=-10

Problem

The docs appear disjoint and not obviously under the umbrella of a unified team, and not obviously official.

Approaches

We could rectify this first with the baby step of a global navigation bar on nix.dev and nix docs without restyling the sites and go from there.

Willing to help?

Maybe, unsure exactly how to approach since the stuff is all separate unrelated code bases at present.

Priorities

Add 👍 to issues you find important.

commented

I propose the following sequence of steps:

  1. Pull out the Nixpkgs and NixOS manuals out of nixos.org into nix.dev at all

    I had started this, but I have lots of higher priorities, so it won't happen in the next weeks. I can share my crufty local branch if anyone is interested in picking it up.

  2. Add consistent-looking style sheets to each of the manuals.

    I was playing with the idea of doing it upstream, but this may need discussion.

    Advantages:

    • Building locally will give you the same result as you'd observe hosted online. Currently this is only the case for the Nix manual, for the reason that there is no styling applied whatsoever.
    • Allows working on style issues independently, since the build setups differ for the current three officially documented projects. There may be more in the future, and keeping those custom information downstream will likely add friction.

    Disadvantages:

    • Duplicates some styling code across projects, with a risk of going out of sync
    • Requires backporting the style additions to all actively supported versions.

Side note: I'm really not a fan of mdBook, it's not very mature compared to e.g. Sphinx. And while that sort of works, I'm not a big fan of Sphinx either. All these static site systems are too simple-minded for our use cases and need hacks and customisation. And highly bespoke usage is really problematic because it tends to be brittle and undocumented, but we need our docs infrastructure to be both powerful and low-tech while meshing with the Git/GitHub workflow.

By low-tech I mean:

  • Commonplace

    Example: CSS instead of some specialist frameworks

  • Straightforward handling

    If you need editor integration to make meaningful contributions, it's too hard to use

  • Small stack

    Learning multiple technologies to be able to manipulate the setup is too much of a barrier. We already impose Nix, Git, Markdown, and all sorts of other random things on contributors.