partial bibliography and structure for ch 01

main
km0 2 years ago
parent 460d9145e6
commit 906269f0d0

@ -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

@ -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
---

@ -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

Loading…
Cancel
Save