refine outline

- remove listing features: this is for marketing
- remove some discussion items: structure already allows referring to
external resources
- adapt software development sections to graphical outline

README.md

@@ -85,10 +85,10 @@ flowchart
 		subgraph dev[software development]
 			direction LR
 			lang-ecosystems[language ecosystems]
-			ci[continuous integration]
-			distributed[distributed builds]
 			caching
 			deployment
+			ci[continuous integration]
+			distributed[distributed builds]
 			cross-compilation
 			bundling[bundling build results]
 		end

contents/README.md

@@ -40,36 +40,26 @@ Each section has the following structure:
 
 Chapters and sections are ordered by increasing level of difficulcy.
 
-
-## Which problems Nix solves
-
-- having complete, automatic build instructions
-- avoiding dependency hell
-- hooking build results into the operating system to make them usable
-
 ## How Nix works
 
-Explain high-level architecture, general mechanism, and design rationale of Nix.
-
-- build system
-- configuration language
-- package manager
-
-@edolstra proposed this to be an appendix. I am convinced a novel paradigm mandates explaining the mechanism first and only then going into details how it applies to specific problems. This chapter should be very concise and make clear the underpinnings, and prominently show diagrams to illustrate the principle. Detailed explanations can follow in chapters on individual subjects.
+Nix offers a novel paradigm to build software and manage computer systems.
 
-Also ultimately, in a hypertext document we don't really care about order, and we can always direct the reader by noting what is to be expected from reading a certain chapter.
+This section briefly explains design rationale, high-level architecture, and general mechanism behind Nix.
 
-## What Nix can do
+- package manager
+- configuration language
+- build system
 
-Each section here should start out with a problem description, and explain the mechanism built on top of Nix to solve that problem. Then there should be concrete examples mapping from the explained concepts to interacting with the actual implementation.
+## What you can do with Nix
 
 ### prerequisites
 
+- required skills and knowledge
 - install Nix
 
 ### build and run software
 
-Show how existing build plans are used to produce working software.
+Here we show how existing build plans are used to produce working software.
 
 - find packaged software
 - run software from existing packages
@@ -103,9 +93,8 @@ Another option would be to develop an approach to the language by motivating lan
 
 ### maintain package collection
 
-Explain how existing packages come into being, how their collection is organized, and show how to modify and create packages.
+Explain how existing packages come into being, and show how to modify and create packages.
 
-- organization of package collection
 - modify existing package
 - create new package
 - contribute to public repository
@@ -115,9 +104,6 @@ In this context they are intended to demonstrate `nixpkgs` architecture and desi
 This should be fairly superficial, otherwise it would duplicate much of the `nixpkgs` manual.
 Alternatively these sections could be dropped entirely, or moved to their own chapter and reference or reuse much of the `nixpkgs` manual.
 
-Another problem with all of the `nixpkgs` topics is that many design questions are still under debate, and implementation is a moving target, even if slowly.
-It is not yet clear to me how to deal with this, it seems like a lot of work, and possibly `nixpkgs` is entirely out of scope of this book if we cannot gather enough humanpower to sort through all of that.
-
 ### declarative configuration management
 
 Show how the disconnected packages from previous examples can be wired up into a consistent and persistent user environment or operating system configuration.
@@ -126,18 +112,13 @@ Show how the disconnected packages from previous examples can be wired up into a
 - operating system distribution
 - service management
 
-@thufschmitt correctly pointed out that tools like `home-manager` and `nix-darwin` are not "official" Nix projects. He uttered concern that discussing them in this book in depth may touch a political issue: Do they become "blessed" by including them?
-
-My stance on this is that they are mature and widely used tools. They should be discussed right next to NixOS already on the principle that they all depend on `nixpkgs` and the way they work is almost identical, illustrating that the mechanism Nix provides is straighforward.
-
-What is not as clear to me is how to determine if and how alternative contenders should be mentioned. There should be some criteria that makes an alternative approach viable enough to discuss, for example being mature enough to reliably support meaningful examples. Another instance that immediately comes to mind are NixOps and Disnix, both of which (to me) have unclear state of maturity and maintenance, but seem to be developed enough and have interesting concepts that I think are worth including.
-
 ### software development
 
-- continuous integration
-- distributed builds
+- language ecosystems
 - caching
 - deployment
+- continuous integration
+- distributed builds
 - cross-compilation
 - bundling build results
     - virtual machines