- 
- **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
- 
- **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
- _???_
- 
- **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
- 
- **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**
- 
- **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
- 
- **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
- 
- _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 ꩜
- 
- **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
- 
- **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
- 
- 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
- 
- 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
- 
- **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`
- 
- **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