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.
173 lines
4.9 KiB
Markdown
173 lines
4.9 KiB
Markdown
- **situated docs**
|
|
- it's a 2 words compound
|
|
- **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** refer to the context of this research
|
|
- fine tuning about
|
|
- kind
|
|
- size
|
|
- of software to look into
|
|
- _situated software_
|
|
- software built around the needs of a community
|
|
- _example_ xpub has a small server
|
|
- server _=_ a machine connected to the www
|
|
- the soupboat
|
|
- _url_ hub.xpub.nl/soupboat
|
|
- it is a shared space online
|
|
- where we can prototype websites, hosting applications, 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 surrounding our tools
|
|
- how different situations generate different documentations
|
|
- and how different contexts resonate together
|
|
|
|
<br>
|
|
|
|
- **a list**
|
|
- to explore the process of sharing knowledge and making worlds together around situated software
|
|
- the plan
|
|
- compile a list of
|
|
- _devices_
|
|
- _thoughts_
|
|
- _tools_
|
|
- _references_
|
|
- _hints_
|
|
- _fieldwork_
|
|
- _excercise_
|
|
- to articulate software documentation as a form of care
|
|
- a list
|
|
- that does not claim to catch everything
|
|
- where order matters
|
|
- but the relations between items matter more
|
|
- a space to define outlines
|
|
- sketch contours
|
|
- and them draw through
|
|
- a soft structure
|
|
- a way to preserve the reality of each item
|
|
- respect the origin of every source
|
|
- without worries of tangling them together
|
|
- the idea for this pubblication is to experiment with the list
|
|
- as a writing machine
|
|
- that seems already fun
|
|
- here some prompts:
|
|
|
|
<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
|
|
- similar to
|
|
- gravitational approach
|
|
- source code as a planet
|
|
- with satellites
|
|
- and orbits
|
|
- **documentation framework**
|
|
- _excercise_ try to map a documentation framework on the ꩜
|
|
- 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 is a lamp
|
|
- 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
|
|
- lamp you bring for camping
|
|
- lamp you put near the bed
|
|
|
|
<br>
|
|
|
|
- **reference**
|
|
- Situated Software, Clay Shirky
|
|
- Situated Knowledges, Donna Harawai
|
|
- List and complexity: Annemarie Mol & John Law
|
|
- Diataxis Documentation Framework, Daniele Procida
|
|
|
|
<br>
|
|
|
|
- 
|
|
- the spirit animal of the developer is the tanuki
|
|
- like racoons they collect resources from the internet
|
|
- they patch together an answer from stack overflow and one from git
|
|
|
|
<br>
|
|
|
|
- 
|
|
- how to navigate the river of softwaru
|
|
- how to structure the thesis writing machine ?
|
|
- Which level of granularity ?
|
|
- I would like to work with small text files
|
|
- but then the parsing could be trublesome ?
|
|
- small frontmatter files ?
|
|
- every entry of the list is a different file ?
|
|
- that is crazy, it would be much better to work with a DB
|
|
- but the db is obscure and requires CRUD
|
|
- that is not a problem...
|
|
- but i would prefer to have the files with the text thereeee
|
|
- writing the thesis in git
|
|
- git writing workflow
|
|
- wait also true that the thesis and the project are two different things
|
|
- but still
|
|
- everything is a file?
|