You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
312 lines
8.1 KiB
Markdown
312 lines
8.1 KiB
Markdown
- 
|
|
- **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>
|
|
|
|
- 
|
|
- **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>
|
|
|
|
- 
|
|
- **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>
|
|
|
|
- 
|
|
- **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>
|
|
|
|
- 
|
|
- **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>
|
|
|
|
- 
|
|
- **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>
|
|
|
|
- 
|
|
- _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>
|
|
|
|
- 
|
|
- **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>
|
|
|
|
- 
|
|
- **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>
|
|
|
|
- 
|
|
- 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>
|
|
|
|
- 
|
|
- 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>
|
|
|
|
- 
|
|
- **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>
|
|
|
|
- 
|
|
- **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
|