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.

395 lines
10 KiB
Markdown

This file contains invisible Unicode characters!

This file contains invisible Unicode characters that may be processed differently from what appears below. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to reveal hidden characters.

![trolley de la muerte](img/trolley.jpg)
- _kamo_ _he/hum_ _IT_
- background
- development of custom software
- to facilitate
- agency-on
- comprehension-of
- complex systems
- before XPUB
- tools were never the main focus
- just instruments to be activated
- within particular contexts
- tailored to specific moments
- then forgotten
<br>
- During first year at XPUB something changed
- Working together with my classmates
- let me realize the importance of
- sharing tools
- develop not just for myself
- but also for others
- together with others
- **code as common**
- importance to create a space
- for these tools to circulate
- importance to build narrations
- around these instruments
<br>
- Prototyping writing machines
- to keep track of what's happening around us
- _CMS_
- [wiki based](/soupboat/padliography/)
- [git based](/soupboat/~kamo/)
- [jupiter notebook based](/soupboat/si16/)
- _Cookbooks_
- [soups](/soupboat/soup-gen/)
- [reading methods](https://issue.xpub.nl/18/06/)
- _Notation systems_
- [to annotate images](/soupboat/si16/annotation-compass/annotate/Naamloos 1.png/)
- [to annotate synth](https://hub.xpub.nl/soupboat/workbook/instruments/test_instrument/add)
- _Web-to-print_
- [click to print 80 000 post-it](/soupboat/postit)
- [libretto for emergent opera](https://issue.xpub.nl/18/03/)
- [this and other lists](..)
- collecting things
- connecting things
<br>
- Every machine implies a different way to think
- requires to balance between different priorities
- accessibility
- susteinability
- flexibility
![goat and cheese](img/sheep_rider.jpg)
- Software development
- as a form of publishing
- as a form of care
- how to
- weave together multiple voices
- open to diverse knowledges
- share pov around software
- _??????_ _?_ _??_ _????_
<br>
- Started thinking about **documentation**
- interesting surface
- interface between
- code
- user
- developer
- world
- **not just as technical writing**
- **but also worldbuilding**
- to orientate code in the world
- everything is a file
- everything is a frog
![pad as frogs](https://git.xpub.nl/kamo/pad-bis/media/branch/master/lifecycle.jpg)
- README.md driven hackpacts
- [Readme Driven Development, Tom Preston-Werner](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- Documentation for the Padliography (with frogs)
- Documentation for the Workbook (with Supi)
- funny cover images _[1](https://git.xpub.nl/kamo/souptxt)_ _[2](https://git.xpub.nl/kamo/pad-bis)_ _[3](https://git.xpub.nl/kamo/kiwiboat)_
- writing docs together (with Chae) _[4](https://git.xpub.nl/manetta/flask-example/src/branch/documentation)_
- now i get triggered whenever doc is mentioned
- realized that writing doc is HARD
- and a couple of other things
<br>
- _contradiction_
- frustration while dealing with undocumented software
- and at the same time never documenting anything
- [xquisite branch on git](https://git.xpub.nl/kamo/exquisite-branch)
<br>
- _participation_
- lack of documentation
- is a barrier
- for the participation of diverse knowledges
- in the the making of software
- At the same time
- this very lack
- could be a starting point
- A space to reclaim given margins and entry points
- A chance to overwrite what is normalized
- Let more voices participate
- in the discourse that is software
- _examples_
- [RTFM, Mara Karayanni](https://psaroskalazines.gr/pdf/rtfm_zine_screen.pdf)
- [Post-Meritocracy Manifesto, Coraline Ada Ehmke](https://postmeritocracy.org/)
![chae api drawing](img/chae_api.jpg)
- Chae drawings to explain API
![supi flask design](img/supi_flask.jpg)
- Supi design to diygest Flask
<br>
- _worlding_
- a way to produce narrations around software
- create a world for the code to inhabit
- to give affordances
- stretch what is possible
- to do or to think with it
- [The Screenless Office, Brendan Howel](http://screenl.es/)
<br>
- **recap**
- community tinkering with code
- lot of experiments
- scattered all around
- not very public
- a generous group
- willing to share
- knowledge & software
- documentation seems an ideal surface
- to host ideas in close contact with code
- letting them entangle and shape each other
<br>
- elevator pitch starts after 12 min of intro
- **what do you want to make?**
- a small documentation framework
- focused on the development of situated software
- in the context of our group in XPUB
<br>
- situated software
- requires
- situated documentation
<br>
- So is this just a documentation of the Soupboat?
- yes
- no
- it's two things
- it starts as documentation around the Soupboat
- to develop a documentation framework for situated software
- chicken-egg meme
<br>
- _docs_
- **a soft index of our software**
- what do they do
- where to find them
- how to use them
- from where they come from
- and where are they going
- how we are documenting them
- how to contribute
- why are they important for us
<br>
- this docs is for two kinds audience
- _internal public_
- that would be us
- offer a way to keep track
- orientate knowledge
- share a common interface
- _external public_
- a way to navigate the Soupboat
- a rich ecosystem
<br>
- _framework_
- could a [standard documentation framework](https://diataxis.fr/) work for us?
- not sure!
- our 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 curate a list of resources
- a framework
- to navigate this network of networks
- with the process of documentation
<br>
- **a system of software & practices**
- a list of
- _references_
- _tools_
- _devices_
- _thoughts_
- _excercises_
- _hints_
- _fieldwork_
- to articulate software documentation as a form of care
- without claim to catch everything
<br>
- shared surface
- one sentence games ritual
- the breakfast club
- flexible and expressive enough
- to be useful for us
- and accessible for others
<br>
- and this is maybe the moment for a small demo???
- [flat markup bonfire](/soupboat/bonfire/)
<br>
- related things
- _url_ [SI16 API](https://hub.xpub.nl/soupboat/si16/)
- A set of functions to mess around with vernacular language processing
- A collective work where everyone contributed with some functions
- Written in Python through Jupiter Notebook
- And documented in the very same notebooks
- With description, examples and references about input and output
- And then aggregated together as endpoints for the API
- _example_ [Shout function](https://hub.xpub.nl/soupboat/si16/functions/shout/)
- A choral API
- with multiplayer approach to documentation
- More docs for the backend is available
- _url_ [si16-backend](https://hub.xpub.nl/soupboat/~kamo/projects/si16-backend/)
<br>
- **the plan**
<br>
- **first 3 months** passed experimenting with documentation
<br>
- the **next 3 months** are focused on
- _internal public_
- here i see myself as facilitator
- introducing the framework
- january is for offering them to the group
- adjusting it together
- februray is for prototyping software & practice
- march is for using the framework to curate an index of the Soupboat
<br>
- the **last three months** are dedicated to
- _external public_
- here i see myself as curator and designer
- to make our doc accessible from the outside
- our group will be busy with the projects
- writing contents for the documentation
- with the aid of the doc framework
<br>
- and then?
- after xpub?
- well i can see myself joining a new community!
- would it be another study program, a coop, a studio
- bringing the methods developed with this framework
- and adjust
- according to the new situation
<br>
- **references**
- Situated Software, Clay Shirky
- Post-meritocracy Manifesto, Coraline Ada Ehmke
- Situated Knowledges, Donna Harawai
- List and complexity: Annemarie Mol & John Law
- Diataxis Documentation Framework, Daniele Procida
- [Readme Driven Development, Tom Preston-Werner](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- Software Studies Revisited, W H K Chun, W Soon, N Wardrip-Fruin, J Zhu
<!--
- **larger context**
- Software
- comes from a really specific occidental cultural tradition
- tends to priviledge
- masculine
- binary
- exploitative
- extractive practices
- technical obscurity
- comes invisible
- transparent
- neutral
- Software models the world
- in order to control it
<br>
- To make software means not only to write code
- but also to take a stance regarding this trends
<br>
- Coding is not just production of software
- but also production of knowledge
- the choice of
- a particular programming language
- the coding style
- the development environment
- the infrastructure that runs the code
- and so on
- are the result of specific contingencies
<br>
- These contingencies are situated in precise contexts
- and these contexts are different one from another
- Programming is not just sharing code
- but sharing context
<br>
- Programming means to provide a point of view
- a perspective to look at the world
- before attempting to get some grip onto it with a script.
<br>
- source code speaks for itself
- but cannot always cast light to its surroundings
- to make place for code
- a necessary act of care
- in the process of sharing knowledge
<br>
- This does not mean to constrain the usage of some piece of software
- or provide opinionated solutions or tutorials
- but rather letting others know where does this code come from
- and where it would like to go
<br>
- resources of various nature
- tools
- thoughts
- anecdotes
- excercises
- prompts
- strategies
- ...
- entry points
- to articulate _software documentation_ as a form of care
<br> -->