writing-list/txt/situated_doc.md

-   ![woodpicker that woodpicks](img/pic.jpg)
-   **situated docs**
-   it's a 2 words title
-   **docs** stands for documentation
-   user manual
-   instructions
-   guidelines
-   tutorial
-   the documentation of coding related practices
-   software documentation
-   instruction on how to use and make software
-   how to be a developer™
-   or how to do things with code without being a developer™
-   that is actually the case for most of the people that enjoy coding
-   or a way to enjoy coding more
-   **situated** refers to the context of research
-   which kind of software to look into
-   _situated software_
-   site specific software
-   social specific software
-   sss
-   built around the needs of a community
-   that can rely on the social infrastructure they come from
-   specific instead of generic
-   that don't need to scale
-   that don't need to solve every problems
-   our software

<br>

-   ![woodpicker hiding](img/hid.jpg)
-   **example**
-   xpub has a small server
-   `server = machine connected to internet`
-   we call it
-   Soupboat
-   _url_ `https://hub.xpub.nl/soupboat`
-   a shared space online
-   where to experiment
-   publish websites
-   host applications
-   prototype tools
-   etc
-   a place to call home in the internet
-   very public yet very intimate
-   how to share knowledge about
-   how to run
-   how to manage
-   how to configure
-   our server
-   _?_
-   could this knowledge be useful for others than us
-   could this small system support others similar ones
-   _??_
-   how situated knowledges inform the knowledge around our tools
-   how different situations generate different documentations
-   how different contexts resonate together
-   _???_

<br>

-   ![woodpicker that hides](img/hole.jpg)
-   **the plan**
-   these software are situated in specific contexts
-   and contexts are different one from another
-   there is not a _single_ _simple_ _smart_ solution™
-   no one size fits all
-   what is there though are some common features
-   small scale and tempo
-   a sociality around software
-   an economy of different knowledges
-   so the plan is research through these aspect
-   and compile a list of resources
-   to navigate this network of networks
-   with the process of documentation

<br>

-   ![list](img/list.png)
-   **a list**
-   to explore the process of sharing knowledge and making worlds together around situated software
-   compile a list of
-   _references_
-   _tools_
-   _devices_
-   _thoughts_
-   _excercises_
-   _hints_
-   _fieldwork_
-   to articulate software documentation as a form of care
-   without claim to catch everything
-   where order
-   matters
-   but relations between items
-   matter more
-   a space to sketch contours
-   and then draw out the borders
-   a soft structure
-   to connect different practices
-   to respect the consistency of every items
-   without worries of tangling them together
-   a texture where to weave
-   different voices
-   different registers
-   different genres
-   different entry points
-   a list as writing machine
-   seems already fun
-   ehe
-   ahah
-   **here some prompts to explore the list format**

<br>

-   ![dough](img/dough.png)
-   **documentation as a form of care**
-   _care for who?_
-   the actors involved
-   (human and more-than-human)
-   developer
-   user
-   community
-   everyone in the range of 1km from the source code
-   aha it's a nice image
-   because the source code is not just in 1 place
-   but cloned in different machines
-   care for the future life of the software
-   and for the future users
-   _care for what?_
-   infrastructure
-   accessibility
-   environment
-   ethical values
-   moral values
-   what was the difference again?
-   between infrastructure and ethical values

<br>

-   ![a pan](img/pan.jpg)
-   **the making of software as a** ꩜
-   source code is at the center of the ꩜
-   with all the other actors ꩜ing around
-   one can get into the making of software from a distance
-   size of the ꩜ is related to
-   the distance from the source code
-   documentation is following the ꩜
-   distance from the center is related to specificity
-   more distant
-   less technical

<br>

-   ![a crab](img/crab.jpg)
-   _excercise:_ try to map a documentation framework on the ꩜
-   ex: the diataxis
-   swirling from the outside
-   _tutorials_
-   learning oriented
-   basic competence
-   familiarize with the documentation
-   lesson
-   ꩜ing toward
-   _how-to_
-   goal oriented
-   series of steps to make something
-   like recipes
-   _explanation_
-   understanding oriented
-   discussion
-   how does it work
-   why it works like this
-   inner whirls
-   _reference_
-   information oriented
-   dry
-   technical description
-   a list
-   to consult
-   not to read
-   center of the ꩜
-   _source code_
-   **but**
-   this is just one version of it
-   could it be different?
-   what happen if we put the person at the center
-   if we put the code on the edges
-   or along the ꩜

<br>

-   ![Moon](img/moon.png)
-   **software and gravity**
-   source code as a planet
-   similar to the ꩜
-   gravitational approach
-   satellites
-   and orbits
-   something about velocity
-   speed of things related to code
-   near the source code
-   things change quickly
-   far from source code
-   documentation
-   coding practices
-   take more time to adjust
-   code moves at the speed of light
-   because it moves into fiber optic cables
-   it ages fast
-   its tempo flows at a total different pace
-   compared to the pace of life

<br>

-   ![Lamp](img/light.jpg)
-   **software is a lamp**
-   if software illuminates an unknown, it does so through an unknowable, wendy h k chun
-   documentation is the light
-   you can see the lamp if the light is lit
-   if it's not lit the lamp is there but you cannot see
-   can you use other lights to see the lamp _?_
-   every lamp has its own light
-   which
-   kind of light
-   kind of lamp
-   you bring for camping
-   you put near the bed
-   there is no such a thing as undocumented software
-   because without documentation you cannot see it
-   as a piece of code would print to the stdout
-   i am documented therefore i am

<br>

-   ![tanuki](img/tanuki.jpg)
-   the **spirit animal** of the developer is the tanuki
-   like racoons they collect resources from the internet
-   they patch together snippets from
-   stack overflow
-   youtube video tutorial
-   git issues
-   forum
-   thread on reddit
-   code as an objet trouvé
-   a dumpster diving approach to coding
-   a matter of urgency
-   a basic need
-   seeing software happen
-   holding working code in your hands
-   is more important
-   than understanding it 100%
-   there is always time

<br>

-   ![river](img/river.jpg)
-   the list and **the river**
-   waters are shallow
-   small text files are ok
-   how to navigate a full thesis _?_
-   swim
-   what about deep waters
-   wait
-   friendly reminder that
-   wet
-   thesis and the project are two different things
-   but go together
-   _git_ writing workflow
-   issues to annotate

<br>

-   ![udon](img/udon.png)
-   **about** this writing machine
-   it is a _web-to-print_ app
-   written in `Python`
-   using `Flask`
-   takes a plain text list
-   written in `Markdown`
-   and renders it in the browser
-   as `HTML` document
-   with some style and formatting
-   so i can think through the form of the list
-   while writing
-   im using a _web-to-print_ approach
-   because formatting with `CSS`
-   is really handy
-   sorcery
-   conjuring the list
-   the list can shuffle a lot
-   without extra work
-   find it on _git_
-   _url_ `https://git.xpub.nl/kamo/writing-list`

<br>

-   ![reference](img/reference.jpg)
-   **references**
-   Situated Software, Clay Shirky
-   Situated Knowledges, Donna Harawai
-   List and complexity: Annemarie Mol & John Law
-   Diataxis Documentation Framework, Daniele Procida
-   Software Studies Revisited, W H K Chun, W Soon, N Wardrip-Fruin, J Zhu
-   Images from
-   Sumiyaki Monogatari, Takeno Shigeyasu
-   (Tales of a Charcoal Burner)
-   amazing manga
-   100% offtopic
-   e va be
-   when you like something
-   you wanna share it