writing-list/txt/framework.md

![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 Karaya‌nni](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> -->