From 906269f0d0a715d9f570a68a436ab56005698584 Mon Sep 17 00:00:00 2001 From: Francesco Luzzana Date: Tue, 7 Feb 2023 16:30:54 +0100 Subject: [PATCH] partial bibliography and structure for ch 01 --- bibliography.md | 20 ++++++++------------ chapters/00_intro.md | 5 ++--- chapters/01_lowering_barriers.md | 27 ++++++++++++++------------- 3 files changed, 24 insertions(+), 28 deletions(-) diff --git a/bibliography.md b/bibliography.md index 70d5787..9dfd2ec 100644 --- a/bibliography.md +++ b/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. -Marino, M.C. (2020). _Critical code studies._ Editorial: Cambridge, Massachusetts: The Mit Press. +- 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. +- 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 diff --git a/chapters/00_intro.md b/chapters/00_intro.md index c8df7a2..0ef6951 100644 --- a/chapters/00_intro.md +++ b/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 --- diff --git a/chapters/01_lowering_barriers.md b/chapters/01_lowering_barriers.md index 080e4f8..a40114c 100644 --- a/chapters/01_lowering_barriers.md +++ b/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 consulted not just from beginner, but also experienced users #a code companion - different docs for different readers + it's often first thing one reads when approaching software - see getting started + it's consulted not just from beginner, but also experienced users - see a code companion 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