thumb

contents/ass.md

@@ -1,89 +0,0 @@
-A list of things made in these two years at xpub
-
-
-- a spreadsheet to chat converter
-- a web design 101 workshop 
-- a bookmarking tool for pads
-- a tool to annotate images
-- a tool to annotate images together
-- a documentation website for a vernacular api
-- a backend for a vernacular api
-- a tool to stick HTML sticker on webpages
-- a prototype to publish 100 puzzles with 100 pieces each, but shuffled in the boxes
-- a git-to-web-to-print system to print 80000 post-it
-- a cms for birthdays
-- a cms for soups
-- a cms for modular synth patches
-- a shared single file CMS to document projects
-- a .json cms
-- a .md cms
-- a jupiter notebook cms
-- a single .1dl file cms
-- a cms for my projects in multiple versions
-- a system to navigate web pages drawing virtual cables
-- a framework to generate interactive synth panel from svg files
-- a small sequencer inspired by tidal mini notation
-- a series of experiment to play music from audience smartphones 
-- some experiment with web audio api
-- a playlist that is a map that is an instrument to perform an opera piece
-- a multi-author web-to-print libretto for an emerging opera
-- a small shared snapshots archive, to keep track of the evolution of projects
-- a branching version of exquisite corpse (drawings)
-- a branching version of exquisite corpse (writings)
-- a guide on how to interact with the mediawiki api from our self hosted server
-- a tool to cut pdfs
-- a writing machine to write text by tags
-- an interactive birthday card
-- a tool to weave together different texts with different patterns
-- a git-to-web publishing system
-- a flat markup language
-- a syntax highlighter for that markup language
-- a csv-to-midi sequencer
-- a subtitle oriented web timeline
-- a multi-input multi-output real-time drawing app
-- a series of activities concerning code documentation
-- a zine with prompts to write code documentation
-- a series of sticker with memes about programming
-- a git-to-web-to-print system for writing the thesis
-- a thesis
-- a publishing house focused on republishing and amazing cover with animals
-- a gloubound book about object oriented ontology
-- a thick booklet about shaping things
-- a thin booklet about literate programming
-- a gluebound book about uxn programming
-- a thick stapled manual for a clone of the apple ii
-- a transparent jacket for computer power and human reason
-- a 1m scroll with articles about the lore of the internet
-- a gluebound book with 3d printed cover about chelsea manning
-- a cute booklet about plan 9 from bell labs
-- some ascii art animations
-- a tool to list all the PZI wiki pages in an almanac
-- a concert in varia
-- a lot of jam sessions with my friends
-- a jam session and live coded live drawn live visual
-- a word-based drum machine
-- a percussions piece made in the park with water bottles
-- a series of live coded jingles for weekly audio pubblications
-- some documentation workout
-- experiments concerning code documentation
-- writing machines for writing documentation
-- partition with debian
-- started using vim
-- an app to sketch storyboards for my gb gf
-- another bookmarking tool using the wiki as backend
-- 3d printed legs to make your server run 4x times faster
-- a writing machine to tinker with the list format
-- a hand drawn videomapping + css live coding tool
-- a website you can visit just once and then it's gone
-- a series of readme files
-- a lot of cover for those readmes
-- a system to update the wiki from our server
-- a rolling fanfiction about katamari
-- versioned essays
-- chimeric api, versioning tiger dingsun
-- the murderous history of loot boxes, versioning Austin Woods
-- different backends
-- some glue for a collective api
-- a karaoke republishing tool (record and replay your text on your midi!!)
-- a script to add new contents to it
-- a system of webhooks to update contents on the soupboat by webhook

contents/care_for_code.md

@@ -1,126 +0,0 @@
----
-title: Care for code - Documentation session
-css: care.css
----
-
-Two hours of headspace to write some _code documentation_. For your new coding project, for the cryptic library you downloaded recently, for a script that you want to share with others!
-
-Too many pieces of code are left alone out there: without an entry point, forgotten, while outside is raining. Wouldn't it be nice to take care of them?
-
-Enter the documentation sessions. Two hours where to sit with source code and write something about it. From simple instructions to in-depth explanations, or maybe some drawings to illustrate the overall process. You name it.
-
-Writing documentation is tricky! But let's face this together: prompts and suggestions will be offered for inspiration, and coffee and snacks for restoration. If you want there will be space to share your work and exchange feedback, if not no prob: just enjoy the cozy music and write some docs.
-
-###  Why documenting when one can "just" code?
-
-These sessions grow out of the contradiction of being frustrated in having to deal with undocumented pieces of software, and at the same time never documenting anything. While for sure there is some thrills in understanding how to stitch codes together, the lack of documentation poses a great hindrance for the participation of diverse knowledges in the making of software.
-
-At the same time, this very lack of documentation could be used as a starting point.
-
-Documentation is a space that interfaces between the code, the user, the developer, and the world. A space with potential to renegotiate and reclaim given margins and entry points. A chance to overwrite what is normalized, and let more voices participate in the discourse that is software.
-
-Documentation is a way to produce narrations around software. To create a world for the code to inhabit, to stretch what is possible to do or to think with it. Documentation is a space for the political in the software. A surface that could host ideas in close contact with code, letting them entangle and shape each other.
-
-## Ok ok ok ok but where to start?
-
-One can start documenting code in many different ways. Every piece of software and every situation require something slightly different, so it's not that there's a right or wrong way to do it.
-
-Here some prompts!
-<!-- Feel free to add more `??? note that this could be an open repo` -->
-
-### Start from the readers!
-
-For who are you writing this documentation for?
-
-Keep in mind that there are many kinds of reader! Beginners and experienced programmers. Friends and strangers. Contemporary others and future selves. Everyone reading documentation from a their own perspective.
-
-This does not mean that what you are writing has to meet the needs of everyone everywhere all at once. Rather, it's a way to acknowledge that different readers come with different expectations and necessities.
-
-Documentation is not just for beginners: it's a code companion. One never stops reading. Even experienced programmers must refer to docs when first encountering some code, and return to the references when they need a refresher on the syntax of a particular command. Documentation is looking at code from multiple distances.
-
-A useful resource to navigate programmers' needs with documentation is the Diataxis framework proposed by Daniele Procida. By leveraging between practical steps and theoretical knowledge, it charts four main modes of technical writing. Each format comes with its own approach and intentions, and in response to different questions.
-
-_Tutorials_ offer entry points for the newcomers, while _explanations_ unveal core mechanisms for more navigated readers. _How-to guides_ teach how to get the work done, while _references_ report lists of information ready to be consulted. Different documentations for different readers for the same code.
-
-Read more about it at [diataxis.fr](https://diataxis.fr).
-
-![diataxis scheme](https://hub.xpub.nl/soupboat/~kamo/thesis/img/diataxis.jpg)
-
-
-### Start from the code!
-
-Another way to start is by commenting directly the source code.
-
-There are many constraints here: no formatting, limited space, no way to insert images, an exagerate level of technical details, etc. For sure (for sure?) not the place to write a comprehensive manual. These limitations however offer a good chance to focus and explain what the code is doing in the clearest way possible.
-
-Code and comments have their own pace, flow and logic. One does not read code as they would read a traditional text (debatalbe)! It's rare for a script to run in a linear fashion, from top to bottom: more often it jumps here and there, calling functions and methods scattered around the codebase.
-
-Guide your reader!
-
-There are many possible strategies: order the comments progressively, rearrange the functions to follow a more sequential development, organize the code into blocks, link to external references, etc.
-
-In his essay _Literate Programming_, Donald Knuth argued for a paradigm shift in software development:
-
-> "Instead of imagining that our main task is to instruct _a computer_ what to do, let us concentrate rather on explaining to _human beings_ what we want a computer to do."
-
-### Start from an image!
-
-Reading source code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective.
-
-Sometimes an image is worth a thousand words. To illustrate the different steps of a process, or to give an overview of the program's lifecycle.
-
-Flowcharts and Nassi-Schneiderman charts are traditional options in technical writing, but things don't have to be sooo strict and rigorous. Let your visual intelligence and the ones of your readers hanging out together. Offer them other ways to think about code: sometimes it's easier with a concrete metaphor, sometimes with a precise diagram, sometimes with !
-
-![chae api](https://hub.xpub.nl/soupboat/wlist/img/chae_api.jpg)
-Explanation of an API by Chaeyoung Kim
-
-![frogs](https://git.xpub.nl/kamo/pad-bis/media/branch/master/lifecycle.jpg)
-Lifecycle of an etherpad document when stored in the Padliography.
-
-
-### Start with someone else!
-
-Teaming up with others comes with several benefits!
-
-Teaming up reduces the workload on the individual: writing docs is demanding and delicate. It requires focus and care and energies! It requires time! And commitment and generosity! Etc!
-
-Teaming up offers multiple pairs of eyes to keep track of code. Here, even before the release, it's necessary to find a middle ground between different perspectives. People of different technical experience can write docs together! The process is beneficial for both, and the outcomes can result more rich and layered.
-
-Teaming up comes handy to undo assumptions and open more entry points. A shared effort is already a moment of publishing. A way of making meaning together. An occasion to join different knowledges and skills, to broaden participation in the making of software.
-
-## Pairing docs and code
-
-Where to publish the documentation is up to you, and depends on the context your coding with. It could be close to the source code, such as a txt file in the same directory, or a ReadMe in the git repository. It could be more detached and physical: a printed booklet, a poster on a wall, a cheatsheet for references. It could be in a wiki, or in a dedicated website, or generated with docs specific tools such as `Read The Docs`, `Sphinx`, `mdBook`, `vuePress`.
-
-The one and only important thing to keep in mind is: __pair docs and code__.
-
-Documentation is just a snapshot of how a system work. A snapshot situated in a particular moment of time, referring to specific versions, implementations and languages. Be sure to offer this context to the reader! State to which version of the code this documentation refers!
-
-Even worse than not having documentation, is to have docs that feel wrong, and don't match with the code they are documenting.
-
-Here the making of software resembles gardening: code changes continuously, and overflow the specifications of a manual. With care and effort, documenting means to trim and prune and transplant and bend code and explanations together.
-
-Such care requires time and energies, that are not always super available! Here is where the idea of pairing really shines: by providing an explicit reference to the version we talking about we are at least sure of two things: which code and which documentation to look for.
-
-### Mmmmm next what ? ?
-
-I don't know. As a matter of fact documenting requires as much practice as programming, so the best we can hope for is learning by doing. Eventually sharing methods, and tricks, and examples, and resources.
-
-Thank you and do your best! These prompts are part of a graduation research for the Experimental Publishing Master, at the Piet Zwart Institute, Rotterdam. It's about code documentation and worlding around software. You can find a living document here --> [https://hub.xpub.nl/soupboat/~kamo/thesis/](https://hub.xpub.nl/soupboat/~kamo/thesis/)
-
-
-## References
-
-Messy list of references and interesting meterials
-
-- A Wishlist for Trans\*femminist Servers
-- Read the feminist manual, Mara Karajanni
-- Aesthetic programming : a handbook of software studies, Winnie Soon & Geoff Cox
-- Close to the machine, Ellen Ullman
-- A life in code, Ellen Ullman
-- Diataxis Framework, Daniele Procida
-- makeareadme.com
-- Readme Driven Development, Tom Preston-Werner
-- Literate Programming, Donald Knuth
-- franklin ACE 100 operator's reference manual
-- Visualizing a procedure with Nassi-Schneiderman charts, Edmond Weiss

contents/final.md

@@ -1,257 +0,0 @@
-# Hello worlding
-
-In this presentation i will look at the work made across the 2 years & __how it changed my understanding of programming and code documentation.__
-
-__Code documentation as a broad set of practices__: comments in code, readme files, tutorials, guides, references, moments of collective learning, workshops, pair programming and collaborative versioning.
-
-These aspects are __usually marginal in software development__: byproducts surrounding the real thing, extra work, and demand of resources often not available in the scarce economy around documentation.
-
-I would like to focus on these marginal zones, bring them to the center and reflect on how they can enrich practices of programming, __opening entry points and backdoors into the making of software for people that are usually left out__.
-
-The institutional required list of things done during these two years is left in the background, squint your eyes and move the cursor to the edges to see through. 
-
-## Getting startled
-
-- Some previous experience in programming
-- mainly used to develop interactive tools
-- for visual art, performance and dance
-- for corporate web design / development
-
-<br>
-
-- Code to understand our surroundings
-- Code as craftmanship
-- Code as service 
-- Code as solution
-- Code as profession
-- Code as product
-
-<br>
-
-- Enroll in XPUB, meet the group
-- Different backgrounds ~ skills ~ values
-- Different ways of working together
-- __how to program together with different programming knowledges?__
-
-<br>
-
-__started documenting things__
-
-![documentation workout](https://hub.xpub.nl/soupboat/~kamo/static/img/workout.png)  
-_intro on my page in the soupboat_
-
-<br>
-
-
-- First months: incredible
-- New things: self-hosting, soupboat as shared space, terminal, python
-- Terror of modifying files in the soupboat and break everything
-- Timid and minimal edits in homepage
-- Made a lot of different prototypes
-- It's cute to look back and see from where we started
-
-<br>
-
-![screen of soup-gen](https://hub.xpub.nl/soupboat/~kamo/static/img/recap/soup-gen-2.jpg)  
-_soup generator aka our first prototype_
-
-![screen of soup-gen with tech questions](https://hub.xpub.nl/soupboat/~kamo/static/img/soup.png)    
-_doubts for the soup gen_
-
-<br>
-
-- __but also traumatic!__
-- Severe stress after first two SIs
-- Friction and contrast between
-- Care within the group, attention to group dynamics
-- Group expectations and ambitions for projects
-- Deadlines and production plans
-
-<br>
-
-- __Ended up centralizing a lot of technical work 😞__
-- Always available and excited to share / offer skills to make things happen 
-- But not always taking into consideration the overall group engagement with programming
-
-<br>
-
-__realized after many year of collective practice that there's a difference in making something for a group and making something together.__
-
-Started appreciating other kind of values in code
-
-<br>
-
-- the parable of SI18 was healing
-- smaller groups, rotation between caretakers and contributors, weekly releases
-- sometimes difficult give value to things made in such a rush
-- but on the course of the issue something changed
-- at the beginning we were just giving themes or keywords as prompts
-- later on it transformed to __offering formats and inviting particular workflows__
-
-
-
-## From code to code documentation
-
-- These ideas of __invitation, offering, proposal__ resonated a lot
-- especially with the concept of __situated software__
-- aka software made with and within a group
-- __shared infra- and social- structure__
-
-<br>
-
-- code as invitation
-- code as offering
-- code as proposal
-- code as care
-
-<br>
-
-- __when is code offered to others?__
-- at first wondered if the moment of offering and proposal could have been the format of the __demo__
-- _mother of all demos_ vibe
-- but as an approach felt too frontal and binary
-- developer vs user
-- and i didn't feel really connected with _demoscene_
-
-Eventually focused on something closer to home: __the friction between being frustrated having to deal with undocumented piece of software, and at the same time never documenting anything.__
-
-And realized that what I'm interested on besides developing tools, is the moment of development itself. And a way to share that with others it's code documentation. Creating entry points and opening backdoors to the making of software.  
-
-> __Code documentation is an interface between the code, the user, the developer, and the world.__ Living close to the source code, but at the same time being less rigid and more expressive, it seems to be an ideal surface to influence software development practices.
-
-That was more or less the moment when I started being more aware about my and others approach to documentation. And learned how diverse and rich practices of code documentation can be: 
-
-- Putting more efforts in writing readmes
-- Hosting workshops to share code 
-- Organizing documentation sessions to dedicate time to writing docs
-- Making zine with prompts to start documenting: [care for code](https://hub.xpub.nl/soupboat/~kamo/care_for_code/)
-
-![scanned materials for the documentation sessions. some sticker, flyers and text, printed on pink paper](https://hub.xpub.nl/soupboat/~kamo/projects/dyc/gadget.jpg)  
-_Materials printed for documentation session_
-
-![Scan of the zine Care for Code](https://hub.xpub.nl/soupboat/~kamo/static/img/care_for_code.png)  
-_Care for code - zine for Documentation Session_
-
-
-__Code documentation as personal understanding__
-
-![a drawing with a cute bird playing the role of an API between server and client](https://hub.xpub.nl/soupboat/wlist/img/chae_api.jpg)
-
-![a screenshot of a meme with a soaked sweated man trying not to use the analogy of the restaurant to explain the api](https://hub.xpub.nl/soupboat/~kamo/static/img/miri.jpg)
-
-![fancy graphic designed documentation to digest flask](https://hub.xpub.nl/soupboat/wlist/img/supi_flask.jpg)
-
-_Chae's drawing - Miri's meme - Supi's diyry_
-
-<br>
-
-__Code documentation as shared struggle__
-
-![comment in code: ](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_1.png)  
-![comment in code](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_2.png)  
-![comment in code](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_3.png)  
-![comment in code](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_4.png)  
-![comment in code](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_5.png)
-
-_Comments in the code screaming for help_
-
-<br>
-
-__Code documentation as collective practice__
-
-![Documentation for a repeat function with some nice parrot](https://hub.xpub.nl/soupboat/~kamo/thesis/img/SI16_NB.jpg)  
-_Folder with Jupiter notebook files, each with a different piece of documentation for SI16_
-
-![piece of flask documentation written with Chae](https://hub.xpub.nl/soupboat/~kamo/static/img/flask.png)  
-_Writing some documentation for Flask together with Chae_
-
-- __Code documentation as poetic and political writing__
-    - Queer Motto API, The Screenless Office
-- __Code documentation as invitation for others to participate__
-    - SI18 CMS for printing post-it
-- __Code documentation as starting point for further explorations__
-    - See Kiwiboat, that lead to Diffractive Reader, that lead to Pad-bis
-- __Code documentation as a way to question code__
-    - See the discomfort in writing-list, 4x-faster, pad-bis
-
-The project is a restitution of this year long process.
-
-## plans for final publication and grad show
-
-__Code documentation is a marginal practice, often invisible labor, usually left in the background.__ For grad show and final pubblication would like to bring it more to the center.
-
-There will be 2 kind of things at the exhibition
-
-### 1. helloworlding.com 
-
-Is a small website to archive pathways through code documentation practice.
-at the current stage a pathway is an annotated collection of readmes. Readmes are presented with a short intro and link directly at the place where they originally can be found, that is in their repos. 
-
-It will be exhibited on a small screen connected to the Soupboat, for the occasion going on a field trip at the slash gallery.
-
-<style>
-
-.double {
-
-    display: inline-flex;
-    flex-direction: column;
-    vertical-align: middle;
-    line-height: 1;
-    text-align: center;
-}
-
-</style>
-
-
-This archive is a <span class="double"><span>reading</span><span>writing</span></span> machine.
-
-- __reading__ because it's a curated restitution of different practices of code docs
-- __writing__ because it systematizes a research process, offering a surface where to keep track of methods through time, and see through snapshots how they transform over time
-
-<!-- Pathways available at the moment: -->
-
-<!-- 1. welcoming language as a mode of address -->
-<!-- 2. cover arts and visual entry points -->
-
-_For the exhibition the website will work as an invitation, with the possibility to sign in to receive update about new pathways._    
-
-_⚠️ work in progress_
-
-### 2. readme readers
-
-Keyword are:
-__readme republishing__
-__readme readers__
-
-There will be printed snapshots of readme files mainly coming from tools developed in the context of the soupboat, bound together as _readme readers_ by means of a custom, loose binding setup.
-
-These readers will be a snapshot of the current pathways curated in [helloworlding.com](helloworlding.com)  
-
-
-These are aspects of code documentation practices I want to be reflected in the installation setup: 
-
-- __proximity to the code__: as a lens to look at it, as an entry point to let people in. as a bait to lure a tech audience not so used to this kind of discourses about sociality around software. 
-
-- __multiplicity__: many different situations, many different ways to document, not 1 size fits all
-
-- __worlding__: documentation can influence the way we think about code. can create worlds around it. system of values different from ultra optimization, productivity and tech solutionism 
-
-To bring under spotlight a theme that is __a niche in a niche__ requires to create some relatable entry points. Code documentation is a surface in the middle of different kinds of audience, so different kind of entry points are necessary. 
-
-![soupboat with legs](https://hub.xpub.nl/soupboat/~kamo/thesis/img/soupboat.jpg)
-
-That's why for the exhibition im binding the readme readers with __clumsy 3d printed legs__. These legs started as a playful device to make our server run 4x faster, and eventually became one of visible marks of software developed around Soupboat.
-
-As binding device they work as:
-
-- a small pack of goofy creatures in the ecosystem of soupboat
-- a playful display for a usually intimidating material 
-- embracing clumsyness, unfinished and provisional states, tryout and failures, commitment to constant gardening and care for code documentation, its readers and all the surroundings 
-
-![prototype legs binding](https://hub.xpub.nl/soupboat/~kamo/static/img/binding-legs.jpg)
-
-![Prototype legs binding](https://hub.xpub.nl/soupboat/~kamo/static/img/logs.jpg)
-
-### Future
-
-[helloworlding.com]() will work as a hub to continue the research and practice around code docs, like the archive in the soupboat has done these two years.

contents/final_old.md

@@ -1,138 +0,0 @@
-# Ok time to wrap it up
-
-In this presentation i will look at the work made across the 2 years to reflect on how it changed my understanding of code documentation.
-
-Code documentation here is intended as a broad set of practices: comments in code, readme files, tutorials, guides, references etc., but also moments of collective learning, workshops, pair programming and collaborative versioning. 
-
-These aspects are usually marginal in software development: byproducts surrounding the real thing, extra work, and demand of resources often not available in the scarce economy around documentation.  
-
-I would like to focus on these marginal zones, bring them to the center and reflect on how do they enrich practices of programming, opening entry points and backdoors into the making of software. 
-
-The institutional required list of things done during these two years is left in the background, squint your eyes and move the cursor to the edges to see through. 
-
-
-## Brief thesis overview for context
-    
-Excerpts from [Hello Worlding](https://hub.xpub.nl/soupboat/~kamo/thesis/) 
-
-
-> I started this research for of two reasons. The first is that I love programming because is like learning another language: not just a new bag of words and a different grammar, but a whole new way of thinking, a lens through which to look at the world. Coding means __to express ideas with the reduced vocabulary of a programming language.__ As in poetry, these constraints stimulate creativity, and encourage a diligent yet playful approach. Working with different programming languages and on different systems __transforms thinking in multivarious ways, and that is extremely exciting__.
-
-> The second reason is that I want to __share this excitement with others__, especially with my friends. __To be able to think and make sense together of what's happening around us, and come up with alternatives or responses or tools that suit us better.__ Because of the steep learning curve of programming and the other barriers previously mentioned, this has often not been possible. But now we know that there are other ways in, and that it is possible to open up even more.
-
-___
-
-> Code documentation is an ideal publishing surface to create worlds around software, and to orientate software in the world.
-
-___
-
-> The nature of code documentation is __to create entry points for people to participate in programming practices__. To encode and filter knowledge, and ultimately to share it with others. This "nature", however, does not come without issues. It makes a __lot of assumptions about who's reading__, expecting experts, or engineers, or dudes. Its __language is unwelcoming__: too dense, too technical, very gendered and unable to address anyone but the neurotypical-white-cis-male programmer. Documentation requires an __enormous amount of care, energy and time to be maintained,__ and it's done always out of budget, always as a side project, always at the end, and only if there's time left.
-
-> Even if it does a questionable job at creating entry points, code documentation still has a lot of __potential as a backdoor__. It's a publishing surface whose reach extends through time and space. Time because **it meets programmers at different moments in their lives: from the _hello world_ till the _how to uninstall_**, and it influences thinking about software continuously, and from different perspectives. Space because it comes in __many different possible formats__, and can shapeshift to serve different occasions: from simple .txt files to entire websites, from coding workshops to comments in the source code to series of video tutorial. The question then becomes: __can we make use of these backdoors to infiltrate programming practices and open more entry points from within?__ 
-
-
-
-## Code documentation as
-
-
-__Code documentation as personal understanding of complicate concepts__
-
-![a drawing with a cute bird playing the role of an API between server and client](https://hub.xpub.nl/soupboat/wlist/img/chae_api.jpg)  
-Chae's drawings
-
-![a screenshot of a meme with a soaked sweated man trying not to use the analogy of the restaurant to explain the api](https://hub.xpub.nl/soupboat/~kamo/static/img/miri.jpg)  
-Miri's meme  
-
-![fancy graphic designed documentation to digest flask](https://hub.xpub.nl/soupboat/wlist/img/supi_flask.jpg)  
-Supi's DIYry
-
-__Code documentation as shared struggle__ 
-
-![comment in code: ](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_1.png)  
-![comment in code](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_2.png)  
-![comment in code](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_3.png)  
-![comment in code](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_4.png)  
-![comment in code](https://hub.xpub.nl/soupboat/~kamo/static/img/comment_5.png)
-
-Comments in the code screaming for help
-
-
-Sessions of pair programming to face technical stress
-         
-__Code documentation as collective practice__
-
-![Documentation for a repeat function with some nice parrot](https://hub.xpub.nl/soupboat/~kamo/thesis/img/SI16_NB.jpg)
-
-Folder with Jupiter notebook files, each with a different piece of documentation for SI16
-
-![piece of flask documentation written with Chae](https://hub.xpub.nl/soupboat/~kamo/static/img/flask.png)
-
-Writing some documentation for Flask together with Chae
-
-__Code documentation as facilitation to distributed authorship__
-
-- post-it generator, git as cms
-
-
-__Code documentation as poetic and political writing__ 
-    
-    - comments in the screenless office
-    - queer motto api readme
-
-__Code documentation as invitation for others to participate__
-
-
-
-__Code documentation as starting point for further explorations__ 
-
-(kiwiboat)
-
-__Code documentation as a way to question code__
-
-
-
-
-## the development of your reading/writing practice across the 2 years,
-
-reading
-
-1
-versioning: search & replace terms in essay to talk about something else
-API as worldbuilding (graphic design => api)
-murderous history of lootboxes (mimic => lootbox)
-
-2
-get to know that something like software studies exist! 
-and it's amazing because software is my passion tm
-birds press, active reading, reading as republishing
-
-writing
-
-dev a lot of small writing machines to write in different ways
-dlist wlist tag pathways soupboat/~kamo 
-readme files and comment in code
-thesis
-
-## the development of your prototyping practice across the 2 years,
-
-software development is my passion
-what i like is: developing tools for others to use
-
-explorations outside the computer:
-birds press and different printing and bookbinding techniques
-3d printing for soupboat and project
-
-
-## your final work and research in the second year,
-
-problematize code documentation practices
-
-organized some worshop and small social gatherings around code development
-printed some zines
-printed some stickers
-writing a lot of readme in many different ways
-
-
-## plans for final publication and grad show (with the understanding that you will continue to work on this after the assessment)
-
-

copycat.py

@@ -0,0 +1,28 @@
+from glob import glob
+import os
+from shutil import copy2
+import frontmatter
+from pathlib import Path
+from PIL import Image
+
+
+
+# from frontmatter import frontmatter
+for folder in glob('projects/*'):
+    project = folder.replace('projects/', '')
+    with open(os.path.join(folder,project+'.md'), 'r') as f:
+            meta, content = frontmatter.parse(f.read()) 
+            if 'cover' in meta:
+                cover = meta.get('cover')
+                file = Path(f'static/img2/{cover}')
+                if file.is_file():
+                    try:
+                        with Image.open(file) as img:
+                            print(f'Ok im copying {cover} to {project}') 
+                            f, e = os.path.splitext(cover)
+                            img.save(os.path.join(folder, f + '.jpg'))
+                            img.convert('RGB')
+                            img.thumbnail((256,256))
+                            img.save(os.path.join(folder, 'thumb_' + cover), 'JPEG')
+                    except:
+                        print(f"Couldn't convert {cover}")

flask_boat.py

@@ -73,6 +73,35 @@ def render_home():
         f.write(render_template("home.html", **home))
         print('Rendered!')
 
+def render_home_thumb():
+    print('Rendering home with thumbnails')
+# with open('/home/kamo/public_html/render.html', 'w') as f:
+        # get the basic info of the website from the /contents/home.md file
+    meta, content = get_md_contents("home.md")
+    projects_list = []
+    for project in list_folders("./projects"):
+        project_info = get_md_contents(f"{project}.md",
+                                    f"./{projects}/{project}")[0]
+        project_date = datetime.strptime(project_info['date'], '%d/%m/%Y')
+        project_info['date'] = datetime.strftime(project_date, '%d %b, %y')
+        project_info['categories'].sort()
+
+        project_info['slug'] = project
+        projects_list.append(project_info)
+
+    projects_list.sort(reverse=True, key=lambda project: datetime.strptime(
+        project['date'], '%d %b, %y'))
+
+    # get the list of the projects, the functions, and the corpora
+    home = {
+        **meta,
+        "content": content,
+        "projects": projects_list
+    }
+    # f.write(render_template("home.html", **home))
+    # print('Rendered!')
+    return render_template("home2.html", **home)
+
 
 # FLASK APP
 
@@ -102,7 +131,8 @@ app.wsgi_app = PrefixMiddleware(app.wsgi_app, prefix='/soupboat/~kamo')
 # Homepage
 @app.route("/")
 def home_page():
-    return send_from_directory(app.root_path, 'render.html')
+    return render_home_thumb()
+    # return send_from_directory(app.root_path, 'render.html')
 
 
 # For generic pages we can include a common template and change only the contents
@@ -115,13 +145,6 @@ def dynamic_page(slug=None):
     return render_template("page.html", **meta, content=content)
 
 
-@app.route("/pres/")
-def pres():
-    meta, content = get_md_contents('final.md')
-    _, awesome_list = get_md_contents('ass.md')
-    return render_template("final.html", **meta, content=content, list=awesome_list)
-
-
 # Single project
 @app.route("/projects/<project>/")
 def p_info(project=None):
@@ -163,4 +186,4 @@ def render():
 
 
 # RUN
-app.run(port="3132", debug=True)
+app.run(port="3132")

projects/3dsub/3dsub.md

@@ -7,15 +7,4 @@ date: 02/03/2023
 description: demo for interactive subtitles timeline
 slug: 3dsub
 title: 3dsub
-git: https://git.xpub.nl/kamo/3dsub
 ---
-
-Prototype for testing the [interactive subtitles timeline](https://git.xpub.nl/kamo/subp). Open with a live server.
-
-Contents in the assets folder:
-
-    3d model of a barbecue in my hometown
-    polypupatic.mp3 from small loops
-    subtitles file with excerpt from the carrier bag of fiction
-
-omg these things are so random, but it’s just for setting things up

projects/almanac/almanac.md

@@ -1,25 +0,0 @@
----
-categories:
-- Wiki
-- python
-- list
-cover: almanac.jpg
-cover_alt: The ancient 3d book of Piet Zwart Wiki
-date: 10/05/2023
-description: List of wiki pages
-git: https://git.xpub.nl/kamo/almanac
-slug: almanac
-title: Almanac
----
-
-A python script that connect to the PZI Media Wiki API, and compile a list with the title of all the pages.
-
-To run:
-
-```
-python3 almanac.py
-```
-
-It's going to save the list in alphabetic order into the `list.txt` file.
-
-[here is the list (updated at 10/05/2023)](https://git.xpub.nl/kamo/almanac/raw/branch/main/list.txt)

projects/chaotic-evil-puzzles/chaotic-evil-puzzles.md

@@ -11,7 +11,7 @@ categories:
   - Games
 ---
 
-## There are 100 lot boxes with 100 different jigsaw puzzles of 100 pieces.*  
+## There are 100 lot boxes with 100 different jigsaw puzzles of 100 pieces.*
 ![100 boxes compose the face of aymeric if seen from a precise point of view](https://hub.xpub.nl/soupboat/~kamo/static/img/100-boxes.jpg)
 _\* (exact quantities to be defined)_
 
@@ -22,39 +22,39 @@ Each puzzle is an A2 sized image displaying the works we did during this trimest
 
 _f.e. A puzzle could be the rules for an RPG; or the map of a bitsy game with some critical texts about gamification; a generated maze, a fan fiction, the glossary, the list of one sentence games, etc._
 
-In other words, the collection of puzzles will be a sort of inventory of our research framed in the form of jigsaw. 
+In other words, the collection of puzzles will be a sort of inventory of our research framed in the form of jigsaw.
 
 ## The pieces are scattered through all the loot boxes, in a way that each one contains parts of multiple puzzles.
 ![shuffle of the jiigsaw pieces](https://hub.xpub.nl/soupboat/~grgr/static/img/jigmix.png)
 
 This could be done in a meaningful way: the idea is not to have total random pieces, but legible fragments from each content.
 
-## When players buy the loot box they can compose the puzzle, but the result is a patchwork of different images. 
+## When players buy the loot box they can compose the puzzle, but the result is a patchwork of different images.
 ![in each loot box there is a patchwork of different puzzles](https://hub.xpub.nl/soupboat/~grgr/static/img/patchworks.png)
 
-If the puzzles have different images but the same pieces pattern, each loot box can have a complete puzzle, but with mixed pieces. In this way we can avoid the frustration that having an  incomplete jigsaw puzzle could cause.  
+If the puzzles have different images but the same pieces pattern, each loot box can have a complete puzzle, but with mixed pieces. In this way we can avoid the frustration that having an  incomplete jigsaw puzzle could cause.
 
-## On the website of SI17 the players can upload their fragments, and compose together an online version to complete all the jigsaw puzzles. 
+## On the website of SI17 the players can upload their fragments, and compose together an online version to complete all the jigsaw puzzles.
 ![demo web interface](https://hub.xpub.nl/soupboat/~kamo/static/img/puzzle-web.jpg)
 
-We can numerate or identify each piece of the puzzles with a code. This could be done when we generate the pattern of the puzzle with Python 👀. To upload a fragment of puzzle, the player is required to insert the code of the pieces, and maybe take a picture. In this way we can be sure that only who has the fragment can insert it online. 
+We can numerate or identify each piece of the puzzles with a code. This could be done when we generate the pattern of the puzzle with Python 👀. To upload a fragment of puzzle, the player is required to insert the code of the pieces, and maybe take a picture. In this way we can be sure that only who has the fragment can insert it online.
 
 
-## Optional feature: users can upload pictures of their fragments and we could have a collective documentation of the work. 
+## Optional feature: users can upload pictures of their fragments and we could have a collective documentation of the work.
 ![demo upload pictures](https://hub.xpub.nl/soupboat/~kamo/static/img/share-puzzle.jpg)
 _This is not unpaid work, it's participation_
 
-Nice feature for the website could be that you can see the digital version of the puzzle, but on mouse :hover we could show the pictures from the public. A puzzle of photos of puzzles. This could be challenging but funny to develop. 
+Nice feature for the website could be that you can see the digital version of the puzzle, but on mouse :hover we could show the pictures from the public. A puzzle of photos of puzzles. This could be challenging but funny to develop.
 
 ## On the website of SI17 there is a community section for exchanging the fragments and complete the puzzle
 ![demo xchange puzzle fragments](https://hub.xpub.nl/soupboat/~kamo/static/img/xchange-puzzle.jpg)
 
-The community section with users and exchange etc could be tricky, but we can stay as simple as possible and do it with Flask. The exchange section should exclude by design the speculation on the pieces or money. A fragment for a fragment. 
+The community section with users and exchange etc could be tricky, but we can stay as simple as possible and do it with Flask. The exchange section should exclude by design the speculation on the pieces or money. A fragment for a fragment.
 
 ## On the website of SI17 the public can access to the experiments, games and researches as well
 ![demo other contents on the website](https://hub.xpub.nl/soupboat/~grgr/static/img/lootbweb.png)
 
-In this way we can provide access to the contents such as the bitsy games, the karaoke video, the ruleset of our games, the reading list, etc. 
+In this way we can provide access to the contents such as the bitsy games, the karaoke video, the ruleset of our games, the reading list, etc.
 
 ### Risk / Benefit assessment
 
@@ -64,10 +64,10 @@ PROS
 + a lot of design
 + not to much code
 + use what we already have
-+ interesting interaction with the public 
-+ performative element ready for the launch 
++ interesting interaction with the public
++ performative element ready for the launch
 + multiple temporalities (individual puzzle, contents, shared puzzles)
-+ world building 
++ world building
 
 CONS:
 - not an API  👀
@@ -80,7 +80,7 @@ CONS:
 The process to make the puzzles could be easy as design - print - cut - shuffle - package, nothing more (+ website)
 
 ![box](https://hub.xpub.nl/soupboat/~grgr/static/img/puzzle-box.jpg)
-The loot box could provide a context and the instruction of the game, as well as the link to the website. 
+The loot box could provide a context and the instruction of the game, as well as the link to the website.
 
 
 ## Scenario
@@ -89,13 +89,13 @@ Mapping the chaotic evil puzzles in the through the different scenari
 
 ### of the form
 
-_scenario 1: The lootbox is a physical box that contains something_ 
+_scenario 1: The lootbox is a physical box that contains something_
 
 Fragments of several puzzles.
 
 ### of the feature
 
-_scenario 7: The items in the loot-box are complementary and it is necessary to connect with other loot-box owners in order to assemble the pieces together._ 
+_scenario 7: The items in the loot-box are complementary and it is necessary to connect with other loot-box owners in order to assemble the pieces together._
 
 There is a single player aspect and there is a collaborative aspect. These two components could be mediated by an online platform, such as the online shared puzzles, but could also work offline if people just combine the pieces of their loot boxes.
 
@@ -103,11 +103,11 @@ There is a single player aspect and there is a collaborative aspect. These two c
 
 _scenario 2: The loot box is a collection of the prototyped games (and researches!) we did so far curated in some kind of form_
 
-The jigsaw puzzle is just a form of encryption of our contents. A shared surface in which we can publish really different things such as a fan fiction, a board game, a link to a video karaoke or a videogame, an essay, the characters of a roleplaying game, etc. 
+The jigsaw puzzle is just a form of encryption of our contents. A shared surface in which we can publish really different things such as a fan fiction, a board game, a link to a video karaoke or a videogame, an essay, the characters of a roleplaying game, etc.
 
 _scenario 3: The loot box is a collection of mini-games + an ultimate game that has to be performed with other players that purcahsed the LB_
 
-There are several layers of playability and access: 
+There are several layers of playability and access:
 
 1. to solve the fragments (single player jigsaw)
 2. to access the contents (games, texts, etc. )
@@ -186,7 +186,7 @@ Thanks and see you sun ☀️
 - short term puzzles (link to multimedia contents, puzzle shards)
 - long term puzzles (hidden messages, 1 word in each puzzles and a secret sentence)
 - size and quantity
-- The jigsaw puzzles results should be secret? There would be much more mistery. Can we reveal only during the launch, but not on the loot boxes? Maybe is a compromise, but maybe is not necessary. Should we reveal them only in the website meanwhile they are completed? Could be.  
+- The jigsaw puzzles results should be secret? There would be much more mistery. Can we reveal only during the launch, but not on the loot boxes? Maybe is a compromise, but maybe is not necessary. Should we reveal them only in the website meanwhile they are completed? Could be.
 - [Generate Jigsaw Puzzle with python](https://github.com/jkenlooper/piecemaker)
 - [How To Laser Cut a Jigsaw Puzzle](https://www.youtube.com/watch?v=xqhOrY8unn4)
 - [Jigsaw puzzle generator](https://draradech.github.io/jigsaw/index.html)

projects/documenting-research/documenting-research.md

@@ -1,45 +0,0 @@
----
-categories:
-- documentation
-- research
-date: 21/03/2023
-description: station skill at the research station
-slug: documenting-research
-title: documenting research
----
-
-### Tagging topics
-
-![pad lifecycle](https://git.xpub.nl/kamo/pad-bis/media/branch/master/lifecycle.jpg)
-
-lifecycle, software, diagram, stack, meme, metaphor, readme, process
-
-_i asked_
-
-- how to convey the structure of a complex system in an accessible way?
-- how to offer entry points for people not familiar with such a system?
-- what could it be a familiar metaphor?
-
-_i did_
-
-- figured out the structure of the system: found out that is a circular process
-- researched for metaphors: lifecycles, environmental cycles, water cycles
-- focused on images targetting kids like elementary school aesthethic, paint-it-yourself drawings, etc. in order to have a really really really accessible metaphor
-- that this is something that should be done during the research! not months later ah ah
-
-
-_i found_
-
-- that using an image let you be more precise and less scared of being precise
-- that this process can happen in different moments ! aha
-
-_i know_
-
-
-![Nassi-Shneiderman chart example](nschart.jpg)
-
-diagram, process, visualization, technical writing, metaphor, flow, branches
-
-![ping pong](https://git.xpub.nl/kamo/drw/media/branch/main/img/pingpong.jpg)
-
-meme, architecture, software design

projects/dyc/care_for_code.md

@@ -1,97 +0,0 @@
-# Care for code - Documentation session
-
-Two hours of headspace to write some _code documentation_. For your new coding project, for the cryptic library you downloaded recently, for a script that you want to share with others!
-
-Too many pieces of code are left alone out there: without an entry point, forgotten, while outside is raining. Wouldn't it be nice to take care of them?
-
-Enter the documentation sessions. Two hours where to sit with source code and write something about it. From simple instructions to in-depth explanations, or maybe some drawings to illustrate the overall process. You name it.
-
-Writing documentation is tricky! But let's face this together: prompts and suggestions will be offered for inspiration, and coffee and snacks for restoration. If you want there will be space to share your work and exchange feedback, if not no prob: just enjoy the cozy music and write some docs.
-
----
-
-These sessions grow out of the contradiction of being frustrated in having to deal with undocumented pieces of software, and at the same time never documenting anything. While for sure there is some thrill in understanding how to stitch codes together, the lack of documentation poses a great hindrance for the participation of diverse knowledges in the making of software.
-
-At the same time, this very lack of documentation could be used as a starting point.
-
-Documentation is a space that interfaces between the code, the user, the developer, and the world. A space with potential to renegotiate and reclaim given margins and entry points. A chance to overwrite what is normalized, and let more voices participate in the discourse that is software.
-
-Documentation is a way to produce narrations around software. To create a world for the code to inhabit, to stretch what is possible to do or to think with it. Documentation is a space for the political in the software. A surface that could host ideas in close contact with code, letting them entangle and shape each other.
-
-## Ok ok ok ok but where to start?
-
-One can start documenting code in many different ways. Every piece of software and every situation require something slightly different, so it's not that there's a right or wrong way to do it.
-
-Here some prompts!!
-<!-- Feel free to add more `??? note that this could be an open repo` -->
-
-### Start from the readers!
-
-For who are you writing this documentation for?
-
-Keep in mind that there are many kinds of reader! Beginners and experienced programmers alike. Friends and strangers. Future selves. Everyone reading the same documentation, but from a diverse perspective!
-
-This does not mean that what you are writing has to meet the needs of everyone everywhere all at once. Rather, it's a way to acknowledge that different readers come with different expectations.
-
-Documentation is not just for beginners: it's a code companion. One never stops reading. Even experienced programmers must refer to docs when first encountering some code, and return to the references when they need a refresher on the syntax of a particular command. They continuously look at code from multiple distances.
-
-A useful resource to navigate programmers' needs with documentation is a framework proposed by Daniele Procida. By leveraging between practical steps and theoretical knowledge, it charts four main modes of technical writing. Each format comes with its own approach and intentions, and in response to different questions.
-
-Tutorials offer entry points for the newcomers, while explanations unveal core mechanisms for more navigated readers. How-to guides teach how to get the work done, while references report lists of information ready to be consulted. Different documentations for different readers for the same code.
-
-Find more at [diataxis.fr](https://diataxis.fr).
-
-![diataxis scheme](https://hub.xpub.nl/soupboat/~kamo/thesis/img/diataxis.jpg)
-
-### Start from the code!
-
-Another way to start is by commenting directly the source code.
-
-There are many constraints here: no formatting, limited space, no way to insert images, an exagerate level of technical details, etc. For sure (for sure?) not the place to write an entire manual. These limitations however offer a good chance to focus and explain what the code is doing in the clearest way possible.
-
-Code and comments have their own pace, flow and logic. One does not read code as they would read a traditional text (debatalbe)! It's rare for a script to run in a linear fashion, from top to bottom: more often it jumps here and there, calling functions and methods scattered around the codebase.
-
-Guide your reader!
-
-There are many possible strategies: order the comments progressively, rearrange the functions to follow a more sequential development, organize the code into blocks, link to external references, etc.
-
-<!-- knuth intro of literate programming -->
-
-### Start from an image!
-
-Reading source code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective.
-
-Sometimes an image is worth a thousand words. To illustrate the different steps of the process, or to give an overview of the program's lifecycle.
-
-Flowcharts and Nassi-Schneiderman charts are traditional options in technical writing, but things don't have to be sooo strict and rigorous. Let your visual intelligence and the ones of your readers hangout together. Offer other ways to think about code: sometimes it's easier with a concrete metaphor!
-
-![chae api]()
-Explanation of an API by Chaeyoung Kim
-
-![frogs]()
-Lifecycle of an etherpad document when stored in the Padliography.
-
-![nassi schneiderman]()
-
-### Start with someone else!
-
-Teaming up with others comes with several benefits!
-
-Teaming up reduces the workload on the individual: writing docs is demanding and delicate. It requires focus and care and energies: it's like gardening, or orthopedics, or cooking, or policymaking.
-
-Teaming up offers multiple pairs of eyes to keep track of code. Here, even before releasing the docs, it's necessary to find a middle ground between different perspectives. Beginner and experienced programmers can write docs together! The process is beneficial for both, and the resulting docs comes with more facets.
-
-Teaming up comes handy to undo assumptions and to open more entry points. A shared effort is already a moment of publishing. Making meaning together. A way to join different knowledges and skills, to broaden participation in the making of software.
-
-## Pairing docs and code
-
-Where to publish the documentation is up to you, and depends on the context your coding with. It could be close to the source code, such as a txt file in the same directory, or a ReadMe in the git repository. It could be more detached and physical: a printed booklet, a poster on a wall, a cheatsheet of references.
-
-The one and only important thing to keep in mind is: pair docs and code.
-Documentation is unfortunately just a snapshot of how a system work. A snapshot situated in a particular moment of time, referring to specific versions, implementations and languages. Be sure to offer this context to the reader! State to which version of the code this documentation refers!
-
-Even worse than not having documentation, is to have docs that feel wrong, and don't match with the code they are documenting.
-
-Here the making of software resembles gardening: code changes continuously, and overflow the specifications of a manual. With care and effort, documenting means to trim and prune and transplant and bend code and explanations together.
-
-<!-- semantic versioning? -->

projects/dyc/dyc.md

@@ -100,65 +100,3 @@ Two hours on ______, starting at ______!
 For people that thinkers with code, no matter the experience.
 Processing, P5.js, TouchDesigner, Javascript, Python, doesn't really matter! All code looks better when is documented!
 Come alone or with friends, bring your laptop and something to document.
-
-## First session 15/03/2022
-
-The first session took place at WdKA, 4th floor. Not super crowded, but still useful to prepare some contents and understand what could be useful.
-
-![gadget](gadget.jpg)
-
-Printed some materials:
-
-__Stickers__
-- Trolley meme
-- Wolf, goat and lattuce meme
-- Diataxis scheme
-
-__Readings__
-- [ReadMe Driven Development - Tom Preston Werner](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
-- [Suggestions for a good README](https://www.makeareadme.com/#suggestions-for-a-good-readme)
-
-### Notes for next session
-
-- Add more context! That could be: something from the thesis introduction
-    - where is this project coming from
-    - why are you doing it
-    - why do you think is important
-- Could elaborate more where the documentation is in relation to the code
-    - where is the documentation?
-    - a (loose) connection between code and documentation
-    - not everyone use git for example
-- Do not take for granted what a readme is! Introduce it!
-    - Some historical overview
-    - [Origin of "Readme" - Stack Exchange](https://softwareengineering.stackexchange.com/questions/96966/origin-of-readme/97132#97132)
-    - [The Jargon File](http://catb.org/%7Eesr/jargon/html/index.html)
-    - Offer it just as an option, mention other options
-    - Critical read of ReadMe Driven Dev
-
-Gathering materials in [Care for code](care_for_code.md)! It came out as a small web-to-print zine!
-
-### Report from session2
-
-Session two at Varia. It was nice.
-
-There were six people including me. Some friends, some acquaintances, and a stranger. It was a balanced mix. In the end we didn't really documented anything, but used the materials and prompts to discuss and think about documentation from different perspectives. We were too invested in the topic to just work on our own.
-
-There were a lot of interesting prompts. Some were coming from the printed materials: the list of sections from _makeareadme.com_ triggered a lot of discussions around the standardization of readme files due to platformism, about what was missing from there, about which kind of world was referring to
-
-Scattered thoughts:
-- next session could be longer: discussions were soo interesting and rich that in the end there was no time for writing docs
-- next session could be thematic: based on one activity such as the seductive readme file, or the readme and easy readme, or image based documentation, etc
-- materials are good starting point, but if you bring something you could also activate it, not just leave it there. meaning: why did you bring a particular thing?
-
-__notes for next time__
-
-practical:
-- offer a structure at the beginning: context, how activities are organized, etc.
-- take pictures
-- take notes or ask if it's ok to record
-
-### documentation archive ???
-
-Hosting the session was refreshing! It helped me think about a concrete outcome (snapshot?) for the graduation project. At some point i found myself thinkingabout a visual archive for documentations with a loose and expressive tagging system.
-
-These tags could be informed by the various activties of the workshops, and be a way to navigate through and link together different docs. Not only from technical aspects but also formal, content wise, etc

projects/exex/exex.md

@@ -1,75 +0,0 @@
----
-categories:
-- Python
-- Tool
-- Writing
-cover: exex.jpg
-cover_alt: uhm not yet here
-date: 10/05/2023
-description: Branching and collaborative writing
-git: https://git.xpub.nl/kamo/exex
-slug: exex
-title: EXEX
-url: https://hub.xpub.nl/soupboat/exex/
----
-
-A branching version of the [exquisite corpse](https://en.wikipedia.org/wiki/Exquisite_corpse) game, forked from the [exquisite branch](https://git.xpub.nl/kamo/exquisite-branch) drawing app developed for [SI17](https://issue.xpub.nl/17/).
-
-Write something, upload it and send the link to someone else: they will continue from your excerpt. With a catch: if you send to just one person the chain will continue linearly, but send it to more people and things will start branching in different directions. 
-
-Could be a writing machine to work on the collective pubblication for the graduation, inspired by what [Kim wrote here](https://pad.xpub.nl/p/gradcollectivexpub).
-
-
-## Install
-
-Clone the repository.
-```
-git clone https://git.xpub.nl/kamo/exex.git
-```
-
-Create a virtual environment.
-```
-python3 -m venv venv
-```
-
-Install the requirements with `pip` and the `requirements.txt` file. 
-```
-pip install -r requirements.txt
-```
-
-Create an `.env` file in the root folder of the project with the following variables:
-```
-DEBUG=True
-FLASK_ENV=development
-FLASK_APP=exquisite_branch
-```
-
-Before running the app for the first time, be sure to initialize the database. __Watch out:__ this will delete the previous instance of the database along with its contents! 
-```
-flask init-db
-```
-After initializing the database you can run the flask application
-```
-flask run
-```
-
-## Overview
-
-Exex saves contents in a database, and join them together in a branching version of the exquisite corpse.
-
-The original exquisite corpse data structure is something similar to a linked list, where every drawing is connected to the previous one. Contents in _exex_ are saved in a database with the same principle.
-
-![Diagram with the situationship of the entries](https://git.xpub.nl/kamo/exex/media/branch/main/linked.jpg)
-
-Each entry in the database has the following properties: 
-
-- `id`: a unique identifier for every entry
-- `branch`: a random name for the excerpt
-- `parent`: the random name of the previous excerpt
-- `content`: the actual content of the writings
-- `username`: the author of the excerpt
-
-When generating the display page, every entry look up its `parent` property to position itself after that.
-
-Mhh should rewrite this better bc is super convoluted ahah. 
-

projects/frana-futura/frana-futura.md

@@ -7,14 +7,10 @@ date: 21/09/2022
 description: "A documentary about environmental fragility of coastal Italy"
 slug: frana-futura
 title: Frana Futura
-links:
-    - title: Subject
-    - url: https://km0.gitlab.io/frana-futura/
 ---
 
 ![Landslide as a timeline](landslide-as-timeline.png)
 
-
 Frana Futura is a documentary that relates the Ligurian landslide condition and the realities that inhabit it, studying past evolutions in order to imagine possible future developments.
 
 Liguria is a fragile and impervious territory in need of continuous maintenance. Neglect and soil consumption, depopulation and conversion into holiday homes, encourage abandonment and accelerate the crumbling of slopes - when they do not become luxurious fortresses.

projects/gpp/gpp.md

@@ -127,10 +127,10 @@ After the work in the past Special Issues, I'm trying to shift from compulsive d
 
 ## Relation to a larger context
 
-Software comes from a really specific occidental cultural tradition.
-Software tends to priviledge masculine, binary, exploitative and extractive practices.
-Software is shrouded in technical obscurity.
-Software comes invisible, transparent, neutral.
+Software comes from a really specific occidental cultural tradition.  
+Software tends to priviledge masculine, binary, exploitative and extractive practices.  
+Software is shrouded in technical obscurity.  
+Software comes invisible, transparent, neutral.  
 Software models the world in order to control it.
 
 To make software means not only to write code, but also to take a stance regarding this trends.
@@ -157,3 +157,5 @@ To make place for code turns to be a necessary act of care in the process of sha
 -   Procida, D. (2017). _Diátaxis Documentation Framework_. `[online]` diataxis.fr. Available at: [diataxis.fr](diataxis.fr) [Accessed 18 Nov. 2022].
 -   Shirky, C. (2004). _Shirky: Situated Software_. `[online]` Available at: [https://www.gwern.net/docs/technology/2004-03-30-shirky-situatedsoftware.html](https://www.gwern.net/docs/technology/2004-03-30-shirky-situatedsoftware.html) [Accessed 11 Oct. 2022].
 -   Ullman, E. (2013). Close to the machine: Technophilia and its Discontents. London: Pushkin Press
+
+‌

projects/postage-free-round-1/postage-free-round-1.md

@@ -1,61 +0,0 @@
----
-categories:
-- Midwives
-- Post
-cover: letter.jpg
-cover_alt: a letter that i receivved
-date: 13/03/2023
-description: Preparing some gift for co labourer
-slug: postage-free-round-1
-title: Postage Free round 1
----
-
-Im grouped with Alex and Jian! It's a good match because Al is working a lot around facilitation, while Jian is actually writing a user manual for her project. Tre bien.
-
-Now let's see brainstorm of what to put.
-
-## Contents
-
-
-
-### Quote from James Bridle - New Dark Age
-
-Technology is not mere tool making and tool use: it is the making of metaphors. In making a tool, we instantiate a certain understanding of the world that, thus reified, is capable of achieving certain effects in that world. It thus becomes another moving part of our understanding of the world – if, often, unconsciously. Thus we might say it is a hidden metaphor: a kind of transport or transference is achieved, but at the same time a kind of disassociation, an offloading of a particular thought or way of thinking into a tool, where it no longer needs thinking to activate. To think again or anew, we need to re-enchant our tools. The present account is merely the first part of such a re-enchantment, an attempt to rethink our tools – not a repurposing or a redefinition, necessarily, but a thoughtfulness of them.
-
-When one has a hammer, goes the saying, everything looks like a nail. But this is to not think the hammer. The hammer, properly conceived, has many uses. It may pull nails as well as drive them; it may forge iron, shape wood and stone, reveal fossils, and fix anchors for climbing ropes. It may pass sentence, call to order, or be thrown in a contest of athletic strength. Wielded by a god, it generates the weather. Thor’s hammer, Mjölnir, which created thunder and lightning when it was struck, also gave birth to hammer-shaped amulets intended to provide protection against the god’s wrath – or, through their resemblance to crosses, against enforced conversion. Prehistoric hammers and axes, turned up by the ploughs of later generations, were called ‘thunderstones’ and were believed to have fallen from the sky during storms. These mysterious tools thus became magical objects: when their original purposes passed away, they were capable of taking on new symbolic meaning. We must re-enchant our hammers – all our tools – so they are less like the carpenter’s, and more like Thor’s. More like thunderstones.
-
-
-### Quote from James Bridle - Ways of being
-
-I would humbly propose three conditions for better, more ecological, machines: machines better suited to the world we want to live in and less inclined to the kinds of opacity, centralization of power and violence we have come to understand as the hallmarks of most contemporary technologies. These three conditions, I believe, are necessary for machines to become part of the flourishing communities of humans and non-humans we’ve sketched out in previous chapters. Our machines should be non-binary, decentralized and unknowing.
-
-Let’s start with non-binary. As we have seen, when we are capable of letting go of yes/no, either/or, zero/one questions – whether in the turbulent flow of analogue computers, the open field of Facebook profiles, or the now tentatively explored operations of the o-machine – we discover not merely new ways of doing and seeing things, more powerful than we ever imagined, but a richness and complexity to the world which surpasses imagination. This is the labyrinth of endlessly significant complexity, the deep, mysterious sumptuousness which Aldous Huxley wrote about, finally acknowledged by our conscious awareness and, potentially, our technology. The world itself is, plainly, non-binary. If we are to act ecologically through our tools, to act with care and justice towards one another and our more-than-human comrades, we must let go of binaries ourselves and free our machines to do likewise.
-
-The non-binary quality of our desired machines also opens them up to a whole body of thought we haven’t so far considered, but that should be central to a rethinking of what computers could be: queer theory. Queer theory opposes the heteronormativity of culture in all its forms, including the gender binary. One of my favourite applications of queer theory to machines is the artist Zach Blas’s project, Queer Technologies, which includes a queer programming language called transCoder and a set of physical ‘gender changers’: computer cables which allow ‘male’ cables to be transformed into ‘female’ ones. ‘By reimagining a technology designed for queer use,’ writes Blas, ‘Queer Technologies critiques the heteronormative, capitalist, militarized underpinnings of technological architectures, design, and functionality.’ Crucially, by actually building the tools it imagines, it makes possible different ways of doing technology and thus of understanding the world that technology is part of.
-
-As the genderqueer activist Jacob Tobia has pointed out, ‘The first time that you heard the term binary, it was probably in a computer class. Here’s the problem: People don’t work like computers. Our identities, our thoughts, and our beliefs can’t always be sorted easily into two categories. In the world we live in, we set up two distinct categories – man and woman – that everyone must choose between. But that doesn’t actually reflect the full diversity of the human experience.’33 As with the conscious decision to remove master/slave terminology from the lexicon of technology, to change the way we describe and build computers could have real repercussions, not only for their own architecture and capabilities, but for the lives of people whose experience is shaped by such technological metaphors – which is to say, all of us.
-
-The second condition, decentralization, draws from the lessons of the octopus and the slime mould to acknowledge the power of communal, cooperative undertaking. The power of communities and systems lies in their intra-action, their becoming-together to produce something greater than their parts. The process of decentralization follows the distribution of networks like the internet, but additionally insists that actual power, rather than mere connectivity, is shared out. We already have the means and know-how to do this, although its actual implementation has hitherto been relegated to the fringes of technological culture by the overbearing pressure of corporate monopolies and corporate profit-seeking.
-
-The open-source movement is one such example of redistribution. This is the practice of publishing the full codebase – every line of code which makes up a piece of software – for public scrutiny and critique. By making the actual code of software and hardware accessible and legible to all, open-source practices decentralize knowledge and provide the basis for collective and self-education. The field of distributed computing is another example: it has given birth to both the extreme democracy of file-sharing and cryptocurrencies and to scientific initiatives like SETI@home and Folding@home. The former seeks to discover life in outer space, the latter to develop new cures to disease. Both use the power of remote processors provided by volunteers – the computers of the general public, linked by the internet – to churn through complex calculations which would overburden any single supercomputer. It’s perhaps unsurprising that both these charismatic – and successful – examples of the form are concerned with life itself. Federated and peer-to-peer networks are a third example of decentralization. These are attempts to recreate the power and affordances of contemporary social networks, website hosts and even video calls, by allowing every user to build, host and control their own fragment of the wider network. In doing this, users actively reshape the network itself, transforming it from one centred around a few, privately owned hubs, to one in which users are directly connected to one another: a change in technology which results in a physical change to the topography and power relationships of the network itself.34
-
-The project of decentralization also encompasses the process of decentring ourselves: the acknowledgement that humans are not the most important species on the planet, nor the hub around which everything else turns. Rather, we are a specialized but equal part of a vaster, more-than-human world, of no greater or lesser significance than any other part. Decentring is a complex task which requires us to think deeply about our relationships with the more-than-human world, and to understand our actions and the tools which we create as contributions to, and mediations with, everything else, instead of as unique, and uniquely powerful, artefacts of human superiority.
-
-The third condition, unknowing, means acknowledging the limitations of what we can know at all, and treating with respect those aspects of the world which are beyond our ken, rather than seeking to ignore or erase them. To exist in a state of unknowing is not to give in to helplessness. Rather, it demands a kind of trust in ourselves and in the world to be able to function in a complex, ever-shifting landscape over which we do not, and cannot, have control. This is a basic imperative of being human in a more-than-human world and has always been acknowledged by traditional cosmologies, through their observance of ritual and their practical entreaties to the intercession of the non-human beings – plants, animals, spirits and weather systems – which enable our survival.
-
-Many of our most advanced contemporary technologies are already tuned towards unknowing, none more so than machine-learning programmes, which are specifically designed for situations which are not accounted for in their existing experience. Applications such as self-driving cars, robotics, language translation, and even scientific research – the generation of knowledge itself – are all moving towards machine-learning approaches precisely because of this realization that the appropriate response to new stimuli and phenomena cannot be pre-programmed. Nonetheless, such programmes can all too easily continue to ignore or erase actual reality – with devastating consequences – if they perceive themselves in the same way that we, their creators, have always seen ourselves: as experts, authorities and masters. To be unknowing requires such systems to be in constant dialogue with the rest of the world, and to be prepared, as the best science has always been, to revise and rewrite themselves based on their errors.
-
-An example of such an unknowing system is the Optometrist Algorithm, developed by Google for Tri Alpha Energy. Tri Alpha is working to develop practical nuclear fusion technology, a source of clean, near-limitless energy which has been the stuff of science fiction for decades. Doing so requires intensely complex calculations, weighing up thousands of variables for each test run of their experimental reactor – thousands more than any human researcher could meaningfully evaluate. But the scale of the problem means that a purely programmatic approach could also lose itself down endless branches of an infinite tree of possibilities, without meaningfully improving the result.
-
-The solution designed in response to this problem was for a machine-learning algorithm to methodically evaluate many options and to present a reduced set of possible actions to a human operator. In this way, not only were more minds brought to bear on the problem, but also at least two distinct ways of thinking: the programmatic, mathematical evaluation of the machine; and the creative, hunch-driven exploration of the human mind. The algorithm works less like a blind, rule-based machine and more like an optometrist trying out different lenses, constantly checking in with their patient, ‘Better like this? Or like this? More like this, or like this?’
-
-The results are promising – but what would such an algorithm look like if it were to appeal not just to the human, but to the more-than-human? An algorithm which devolved part of its processing, part of its thinking, to non-human actors: perhaps something like the bucket of pre-processing water described earlier, or the use of slime moulds and mycorrhizal networks as translators and co-creatives. This would be the full realization of Stafford Beer’s U-machine, or Turing’s o-machine – and crucially, it would be facing outward, rather than trying to trap its colleagues in a little box, further disconnected from the wider world.35
-
-
-An example of a really unknowing cybernetic machine is the Cockroach Controlled Mobile Robot, or Roachbot (2004–2006), Canadian designer Garnet Hertz a device created by the that demonstrates all of the above principles, while also retaining some of the more nightmarish aspects of the spinal dog and the crab computer. (Perhaps we might consider such squeamishness a useful indicator of more-than-human effectiveness, but that is a subject for elsewhere.)
-
-The Roachbot consists of a motorized tricycle, a set of proximity sensors and a very large Madagascan hissing cockroach Velcroed to a trackball. The Roachbot uses the cockroach’s dislike for bright light – the same mechanism which sends them scurrying away when you turn on the kitchen lights – to create a simple, exploratory cyborg robot. As the cockroach scurries on top of the trackball, it propels the tricycle across the room – but if it gets too close to an obstacle, bright LEDs illuminate in that direction, causing it to spin off on a different trajectory. In this way, it makes its way around a space, avoiding obstacles in much the same fashion as Grey Walter’s tortoises. The key difference between the Roachbot and the tortoise is that an element of the system remains unknown to us. Unlike the tortoises, the cockroach at the heart of Hertz’s machine has not been constructed or solved. It’s doing its own thing – it is an oracle. It has in cybernetic terms, been ‘entrained’, but it has not been dominated (although the cockroach itself might argue with that assertion).36
-
-In any true relationship based on unknowing – between human, machine, mushroom or cockroach – the participant must forgo any requirement to fully understand the operation of any other. Rather, relationships based on unknowing require a kind of trust, even of solidarity. They require us to open ourselves to the possibility not merely of other intelligences, but to the idea that they might want to help us – or not – and thus might predispose us to the creation of more mutually agreeable conditions in which they might deign to assist us voluntarily. This is indeed the opposite of helplessness: it makes possible the creation not merely of better relationships, but of better worlds.
-
-## Question for Al & Jian