situated_doc

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

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

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