NixCon 2019 Documentation Task Force Meeting Outcome

Development Documentation
1

Hey everyone,

During NixCon 2019, a group of us met to discuss Nix’s documentation status and
opportunities. :sun_with_face:

The notes for this discussion were recorded:

We chose the following items as our top priorities:

Write an RFC to create a doc team that is responsible for – and can make decisions about – the website.

Contact: @chreekat

Prototype a documentation standard on top of the Flake RFC.

Don’t try to expand the scope of the Flake RFC.

Don’t necessarily create a documentation RFC yet.

Just make sure there are no major blockers to a standardized doc format.

Contact: @chreekat

Manuals should reference each other at the beginning

This is a small item to add some text at the beginning of each document (Nix,
NixOS, Nixpkgs). They should each explain what the reader will find in the
document, and where to go for other parts of the system.

E.g., “This document is about the Nix language, for foo go to manual bar”.

Nix book

This is a big item, so we should break it down further.

The vision is to have a “book” like the rust book for newcomers to start from
scratch, learn fundamental concepts, and gain familiarity with the language and
ecosystem.

Contact: @layus

Prototype a website structure

The goal is a new layout of the top-level information available on the website.
For instance, the “Community” and “Support” sections currently have a mix of
overlapping information that could be better organized and named.

We can do this as a prototype and build on https://builtwithnix.org/.

Contact: @azazel75

Move instructions on how to edit documentation closer to the top

This is a small item. The manuals have sections on how to edit their content,
but they are small and dissimilar. They could be made uniform and more visible.

Move installation section out of nix/nixos manual

Installation instructions are good for tutorials and learning guides, but they
are out of place in a language reference.

Merge nix and nixpkgs manuals

This is a big item. You would not want to simply concatenate the manuals, but
curate and merge sensibly.

The motivation for this change is that most languages do this, and we would have
one place to search. Never look for builtins in the wrong place again!

13 Likes
2

Manuals should reference each other at the beginning

See Doc: various improvements NixOS and Nixpkgs manuals by FRidh · Pull Request #72157 · NixOS/nixpkgs · GitHub. This covers the Nixpkgs and NixOS manuals.

2 Likes
3

Sweet! Looks great, I’d love to contribute to an effort like this. Did anything concrete about moving from Docbook come about? It’s honestly my biggest hurdle. I’d also love to see the website get a small refresher, but that is out of scope for the documentation (though related) :slight_smile:

1 Like
4

Thanks for the feedback!

As a matter of fact, refreshing some pieces of the website are on the list. But :

Concretely, many opinions were expressed, but none of them converged. :upside_down_face:

I guess the syntax for documentation could be considered a variant of syntax for comments. I think we can dramatically improve the usefulness of the documentation without kicking that hornet’s nest.

3 Likes
5

Thank you! Fantastic work.

1 Like
6

10 posts were split to a new topic: Documentation format

9

Also, a topic we didn’t discuss, but an important topic – localization. I know developers who would like to learn Nix/pkgs/OS, but are uncomfortable reading English. They are forced to read a few local-language blog posts, which is bad.

For reference, there is Javascript book project https://javascript.info/, which has collaborative documentation translation integrated with github The Modern JavaScript Tutorial · GitHub. Maybe JS is a bad example as it is highly popular compared to Nix/pkgs/OS.

1 Like
16

I would also be in favor of moving (and keeping) discussions about which format to use to a different thread.

We kind of decided not to discuss this during the hackathon, as there’s a lot of other very important challenges to tackle before the format is even an issue.

The topic of which format to use, while for sure important, is relatively divisive (everybody has their strongly held opinion) and therefore sucks most of the energy out of discussions about documentation.

Since I presume everyone who’s commenting here about format also agrees that we should improve the content, I suggest we keep the two discussions separate, in the interest of the project :slight_smile:

8 Likes
18

Here’s a related PR, changing Support to Learn in the top layout bar.

I personally find learn more pertinent and welcoming to newcomers - in my mind, they’re not looking for support, but rather to learn what the hell this is all about.

Let me know what you think in the PR :slight_smile:

3 Likes