Participants - HackMD

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!

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.