Participants
============

- asymmetric
- azazel75
- chreekat
- danbst
- dpausp
- layus
- rycee
- zimbatm

Action Items
============
- [ ] Write Discourse post showing the top priority items we identified
- Identify the people in the group who were most interested in particular items as contacts
- Just link to this thing
- [ ] Start doing the things :D

Communication
=============

- IRC [#nixos-wiki](https://logs.nix.samueldr.com/nixos-wiki)
- Discourse category [Development/Documentation](https://discourse.nixos.org/c/dev/documentation)

Problems
========

Technical
---------

- Inefficient to render/download documentation
- Closure size is huge
- Docbook
- The documentation-generation framework is too nixos-specific
- rycee wants to reuse it for HM

Editorial
---------

- Outdated docs
- Incoherent docs
- Lack of framework
- What types of docs do we need
- Who are the docs for
- Reference manual is not what a beginner needs, but it\'s the only
thing we provide at nixos.org
- Too many manuals
- Especially, distinction between nix and nixpkgs manuals seems unnecessary
- You never need nix without nixpkgs
- Not always clear if a function is in builtins or lib
- nixos.org has "Support" and "Community" top bars, but the resources within
those pages are a mix of Learning, Getting Started, Community, and variousi
other topics.

Ideas
=====

- In-tree documentation
- e.g. a README at `pkgs/development/ruby-modules`
- the idea is that it's way more discoverable for users
- and it's easier to keep up to date for developers
- reduce closure size to build manual
- convert DocBook to RestructuredText / Markdown / AsciiDoc
- Transcribe Graham\'s beginner talks
- how does the flake RFC affect documentation?
- Responsibility for documentation could be further broken down into: website, learning materials (book, tutorials), and reference manuals
- come up with a framework for documentation
- <https://www.divio.com/blog/documentation/>
- sections like \"if you\'re a python/haskell/x\" developer
- look at [guix](https://guix.gnu.org/) homepage as reference
- they have "guix for HPC/bioinformatics"
- add a comparisons sections
- other Linux distros
- Docker
- Nix book
- see [rust book](https://doc.rust-lang.org/book/)
- Merge nix and nixpkgs manuals
- Most languages document the language and the standard library in the same place
- move installation section out of nix/nixos manual
- the idea is that it's a reference for people who **have**
nix/nixos installed
- Examples of languages with this distinction: Lua
- Move instructions on how to edit documentation closer to the top?
- move language support sections (Nixpkgs Manual) closer to beginning
- Manuals should reference each other at the beginning
- "This document is about the Nix language, for *foo* go to manual *bar*".
- Maybe a "choose your own adventure" style guide would help point people to the right documentation is certain cases? This is, for example, used by the Java library [Reactor](https://projectreactor.io/docs/core/release/reference/#which-operator) for guiding people to choose the right operator depending on what they want to accomplish. For the Nix ecosystem this could be something like:
- I want to …
- package …
- a Haskell application …
- a Go application …
- make the Nix language …
- filter a list using some predicate …
- etc.
- not quite documention, but a way to discover docs. When any of `nix-build/instantiate/env/shell` fails, try to diagnose the error and provide a link to documentation section which discusses/solves this issue
- an interactive demo (interactive SVG, asciicast) on front page
- RFC to create a doc team that is responsible for -- and can make decisions about -- the website.
- Just do what Rust does :)
- Build on https://builtwithnix.org/ ?

Links
=====

Other documentation
-------------------

- <https://docs.python.org/3/>
- <https://nixos.wiki/wiki/FAQ>
- <https://guix.gnu.org/>
- https://www.lua.org/docs.html
- https://wiki.archlinux.org
- https://www.rust-lang.org/learn
- https://guix.gnu.org/

How to write documentation
--------------------------

- https://www.divio.com/blog/documentation

Documentation generators
------------------------

- <https://antora.org> (AsciiDoc)
- <https://sphinx-doc.org> (RestructuredText / Markdown)

# Discourse post draft

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:
https://hackmd.io/lmgvz5fzQymLsnR8QgAHQg?view

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.

[rust book]: https://doc.rust-lang.org/book

Contact: @layus

### Prototype a website structure

Primarily, 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!