partial bibliography and structure for ch 01

bibliography.md

@@ -1,21 +1,17 @@
 ## Bibliography
 
-Ullman, E. (2017). _Life in code : a personal history of technology._ New York: Mcd, Farrar, Straus And Giroux.
+-   Ullman, E. (2017). _Life in code : a personal history of technology._ New York: Mcd, Farrar, Straus And Giroux.
-Marino, M.C. (2020). _Critical code studies._ Editorial: Cambridge, Massachusetts: The Mit Press.
+-   Marino, M.C. (2020). _Critical code studies._ Editorial: Cambridge, Massachusetts: The Mit Press.
+-   Soon, W. and Geoff Cox (2020). Aesthetic programming : a handbook of software studies. London: Open Humanities Press.
+-   Fuller, M., ed. (2008). Software studies a lexicon. Cambridge, Massachusetts Mit Press.
+-   Gabriel, R.P. (1998). Patterns of Software. Oxford University Press, USA.
+-   A Wishlist for Trans\*femminist Servers. 2022. https://etherpad.mur.at/p/tfs
 
 TODO:
 
-add:
-
--   software studies lexicon
--   aesthetic programming
--   patterns of software
-
-how to cite??
-
--   A Wishlist for Trans\*femminist Servers. 2022. https://etherpad.mur.at/p/tfs
-
 https://ironicsans.substack.com/p/the-strangest-computer-manual-ever
 https://www.ironicsans.com/2010/02/they_dont_make_computer_manual.html#comment-403451
+
 https://www.ironicsans.com/ace100.pdf
 https://www.ironicsans.com/ace1000.pdf
+https://knowingmachines.org/critical-field-guide

chapters/00_intro.md

@@ -1,11 +1,10 @@
 TODO:
 
--   groud with a concrete example
 -   adjust second paragraph to better address audience
 -   rephrase quotes ?
--   outline is:
+-   outline of chapters is:
     -   Lowering barriers to
-    -   Welcoming diverse knowledges for
+    -   Welcoming diverse knowledges to
     -   Orientate software in the world
 
 ---

chapters/01_lowering_barriers.md

@@ -1,22 +1,23 @@
 # Who is reading
 
-_could documentation be a surface to build worlds around software?_
+_why documentation as a surface to build worlds around software?_  
+_docs to lower barriers and create entry points_
 
 ```
-build worlds?
+a surface to build worlds?
     where software circulate
     who gets to use it
     political of the software
 
-
 yes because
-    it's often first thing one reads when approaching software # getting started
+    it's often first thing one reads when approaching software - see getting started
-    it's consulted not just from beginner, but also experienced users #a code companion
+    it's consulted not just from beginner, but also experienced users - see a code companion
-    different docs for different readers
 
 yes but
-    it should stop assuming its reader
+    it should stop assuming reader
     it should be more welcoming for different kind of knowledges
+
+leading to: 2. welcoming different knowledges
 ```
 
 ## Getting started
@@ -38,14 +39,16 @@ The initial imprinting of documentation is a vantage point to orientate code in
 
 ## A code companion
 
-The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the specifics of a particular programming language or platform. Sometimes for the web, sometimes for a hardware component, sometimes for a different operative system. These _specs_ make every piece of code a bit alien and peculiar. Tinkering with code is not just knowing by heart a programming language, but rather having to deal with a lot of different recipes for different occasions.
+The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the specifics of a particular programming language or platform. Sometimes for the web, sometimes for a hardware component, sometimes for another operative system. These _specs_ make every piece of code a bit alien and peculiar. Tinkering with code is not just knowing by heart a programming language, but rather having to deal with a lot of different recipes for different occasions.
+
+Documentation is not just for beginners: it's a code companion. One never stops reading. Even experienced programmers must refer to docs when first encountering a software, and return to the references when they need a refresher on the syntax of a particular command. They continuously look at code from multiple distances: close to the source code with lines of comment—ignored by the machine, but much appreciated by fellows developers—or from printed books, along with pages of explanations and use cases.
 
-Documentation is not just for beginners: it's a code companion. It relates with code continuously. Even experienced programmers must refer to the docs when first encountering a software, and return to the references when they need a refresher on the particular syntax of a specific command. One never stops reading. Documentation acts as a portal to different moments in the life of a programmer: from the _hello world_ to the _how to uninstall_.
+This tentacular surface reaches different moments in the life of a programmer: from the _hello world_ to the _how to uninstall_.
 
--   documenting code from different distances
 -   different documentations for different readers
+-   wrap up
 
----
+### previous writings
 
 -   lowering barriers and creating entry points
 -   readme examples
@@ -69,8 +72,6 @@ Cuneiform writing and comments. (even though this is cuneiform writing and synta
 
 ## Different distances
 
-Documentation can happen at different distances from code: directly in source with lines of comment—ignored by the machine, but much appreciated by fellows developers—or it can be printed in books, along with pages of examples and references.
-
 Who is writing could be the very same developer or someone else. Writings come with different approaches and intentions, and as response to different needs.
 
 ## Different documentation for different readers