[Nix-dev] Real documentation, aka "Let's kill the wiki"

[Cillian de Róiste]

2015-11-19 16:57 GMT+01:00 Profpatsch <mail at profpatsch.de>:
> On 15-11-19 02:56am, Roger Qiu wrote:
>> Can the manual be made as a gitbook with the chapters fleshed out better
>> and made more user friendly? One  part of the manual can be very fact
>> based, another part can be story based. Kind of like the difference between
>> documentation vs api documentation vs tutorials. I often find myself across
>> 3 to 4 different blog posts, the arch and gentoo wiki, the nixos manual,
>> the wiki and github issues because the up to date relevant information is
>> everywhere.
>
> May I humbly suggest http://stevelosh.com/blog/2013/09/teach-dont-tell/ as
> a general documentation writing template?

I'm a big fan of https://jacobian.org/writing/great-documentation/

I think it gives a really nice overview of the three main kinds of
documentation:
* step-by-step tutorials,
* overviews and topical guides to the various conceptual areas of your
project, and
* low-level, deep-dive reference material.

It also has some nice ideas such as creating an initial tutorial: "a
new user should be able to experience success within thirty minutes"

Cheers,
Cillian

-- 
NixOS: The Purely Functional Linux Distribution
http://nixos.org