2015-11-19 16:57 GMT+01:00 Profpatsch <[email protected]>: > 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 _______________________________________________ nix-dev mailing list [email protected] http://lists.science.uu.nl/mailman/listinfo/nix-dev
