---
# System prepended metadata

title: Documentation Notes
tags: [documentation]

---

# Documentation Notes

Collecting ideas on how to improve the book (and documentation in general).

Recommended docs by Steve Francia:
* Go
* Stripes
* MongoDB
* K&R C book: Reference + book split

## Current Status
* [Book](https://www.nushell.sh/book)
* [Commands](https://www.nushell.sh/commands)
* [Cookbook](https://www.nushell.sh/cookbook)
* `help xxx` (built-in with slow stdlib re-implementation)
    * aliases, commands, escapes, externs, modules, operators
* `tutor`
* [README.md](https://github.com/nushell/nushell/blob/main/README.md)
* [FAQ for developers](https://github.com/nushell/nushell/blob/main/devdocs/FAQ.md)

## Proposed Structure

* **Book** would be written in a tutorial style covering the basics of all topics of Nushell as a shell and a programming language. Small projects would be a part of the book and would cover the topics (think the Rust book). The book would be non-exhaustive: It would explain basic principles, but for more details, links would be provided to the reference book or even the cookbook (see the next bullets).
* **Reference book** would serve as a look up if you need to dig into something. Its purpose is to offload details from the main book to keep the former short and sweet.
    * Draft on hackmd: https://hackmd.io/hLTipwOaR2K28GzwHrtVGQ
* **Cookbook**: Practical recipes for common tasks. It could also contain the "Coming from XXX" pages.
* `help xxx` would stay as-is?
* `tutor`: Yeah, it would be cool to have an interactive tutor. Not sure what the right fit for it would be, though. We should have something in the REPL that goes beyond the current `help xxx` listings
* README.md
    * Installation shouldn't  list brew and winget as quick install options (we can't assume people have these package managers installed by default; also why these two and not others?)
    * Should we make it shorter by condensing the Philosophy and Goals section?
* NEW! Startup interactive prompt that would let you set up Nushell. To see what I mean, install zsh, and run it witout any config files as if you ran it for the first time. Maybe `tutor` could be related to this?
* NEW! `nudoc`: Documentation format inside comments so that you set more things into command/module/etc. usages (such as runnable examples). Make it possible to generate documentation for a Nushell package.
    * Since we use REPL examples a lot, it could recognize the starting `>` as a prompt marker
* NEW! All code samples used in the Book, Reference Book, and Cookbook should be ran and tested in the CI (as much as possible).
* NEW! Standard library documentation (preferably generated with `nudoc`)
* NEW! FAQ

## The Book!

Here I want to collect the list of topics that should be covered (roughly outlining the chapters / sections) and the list of projects/examples used to explain them. The examples should be meaningful instead of the current random `def spam` snippets. While going through the book, the reader would gradually build up their config files, set keybindings, define a bunch of helper commands, completions, etc. In the end, they would be left with a useful toolbox they built by themselves.

While not a referece, the Book should not be a 100% story mode. The chapters / sections should be self-contained with clearly stated dependencies such that someone can jump straight into what they're looking for.

### Covered Topics

List of topics covered by the Book

* Getting Started
    * (should cover basic installation and basic user experience using vanilla Nushell -- show off batteries included!; no customization yet, that will be covered in next sections)
    * Installation
    * Default Shell
    * Quick Tour (maybe needs better examples / small project?)
    * Moving around your filesystem (merge with above?)
* Configuration
    * Config files and their loading order
    * `nu` flags related to config
    * Hooks
    * Keybindings
    * Themes / colors
* Standard library
* Thinking in Nu (where to?)
    * Add environment (we don't use std::env)

### Project Ideas

* Hot-reloading config on pressing Ctrl+R (would invoke `source $nu.config-path; source $nu.env-path`)

### Topic-Project Match Table

Each topic should be covered as a part of some project. To be filled later after we settle on the topics.

| Topic | Project |
| -------- | -------- |
| Config-Keybindings     | Hot-reloading config     |

### FAQ

> How do I source all files in a directory?

You don't. `use` the directory.

### Common pitfalls

* Flags of externals: `cmd --foo=$FOO` must be `cmd $'--foo=($FOO)'`

### Reference Book

It could contain the following:
* The contents of the [Commands](https://www.nushell.sh/commands) book
* Since we don't have only commands, it would contain the contents of all `help xxx`
* Parts of it could be automatically generated
* All possible and default config values
* Details that don't make it into the main book (e.g., operator precedence, the exact module loading sequence, etc.)

From the current book:
* Nushell cheat sheet
* "Coming from XXX"