km0 2 years ago
commit e4140d7e58

@ -0,0 +1,12 @@
---
categories:
- Web
date: 30/10/2022
description: draw your own b-day cards
git: https://git.xpub.nl/kamo/hbs
slug: birthday-card
title: Birthday Card
url: https://hub.xpub.nl/soupboat/hbs/
---
Just a birthday card that you need to draw yourself, powered by panel.js and spaghetti.js

Binary file not shown.

After

Width:  |  Height:  |  Size: 156 KiB

@ -13,79 +13,123 @@ title: Graduation Project Proposal
## Draft Project Proposal
_note: I'm using the words toolkit, handbook, map, collection of tools, practices or devices as interchangeable. Read it crossing your eyes, as a kind of not-fixed-superposition that will eventually stabilise during the research_
### What do you want to make?
Focus on software documentation as an interface between code, users, developers, communities, and the world.
- A toolkit to explore _software documentation_ as publishing surface.
- An extensible set of tools and practices that focus on _software documentation_ as an interface between code, users, developers, communities, and the world.
- A handbook with a strong attention on the economy of different knowledges present in _software documentation_.
- A collection of small devices to assist and stimulate the documentation process, with prompts and gently reminders that _software documentation_ is a form of care, not just a source of profit.
- A series of writing prompts to experiment with software documentation as a generative device to keep thinking through code from different perspectives.
- A way to understand publishing as iterative process, as a format that grows and shrinks through versioning and embrances branching to adapt to specific environments.
- A (loose, habitable, extensible) map to orientate around what does it mean to _make software_ besides just writing code.
Research how writing software documentation changes depending on the context and actors involved.
- Something in between the refreshing shuffle of perspective in the Oblique Strategies, and the ability to infiltrate established practices like the Lottery of Babel.
- Something to be organized and shared as the Software Design Pattern, but to be discovered and performed as the Minecraft crafting system.
Experiment with software documentation as a generative device to keep thinking through code from different perspectives.
![Political compass of knowledge + references](compass_reference.jpg)
Explore software documentation as iterative process, as a format that grows and shrinks through versioning and embrances branching to adapt to specific environments.
<!-- - To question who gets to write it, who has to write it, who is left out.
- To use it as a writing machine, to build a world around software.
Develop tools to facilitate rich software documentation. To assist and stimulate the writing process with prompts and gently reminders that software documentation is a form of care.
How this exchange of resources could make place for different voices. How writing _software documentation_ changes depending on the context and actors involved? -->
### How do you plan to make it?
Define a domain of research. Where does software documentation begin and where does it end? What about tutorials, guidelines, and demos? How porous or tentacular is this surface?
_note: the plan is to use the different hackpacts and assignments as a way to bootstrap different directions for the research. Every hackpact is self contained and in effect is a different prototype, but it rarelly ends when a new one starts. Rather, with every new hackpact the old ones continue developing in the background with less intensity, but in concert, informing each other._
`[Hackpact 1 - Define a domain of research]`
Where does software documentation begin and where does it end? What about README files, tutorials, guidelines, comments in the source code, and demos? How porous or tentacular is this surface? Set some references by looking back at the works made last year and read them through the axis of code and care. Explore common templates of documentation and their habitability.
#### Work on several prototypes and their documentation
`[Hackpact 2 - Write documentation & focus on its contents and style]`
Write documentation for selected prototypes from the many made last year: could this process create a new public, or transform their original ones?
As initial case study focus on the Padliography, a tool developed within XPUB to keep track of the amount of scattered Etherpad documents used to take notes and work togheter. During last year it's been used only in the context of our class, but after some adjustments it's now flexible enough to be offered also to other constellations orbiting around the _XPUB & Lens-Based wiki_.
What does it mean to offer it to someone else? How to talk the same language with different contexts? How to be clear without oversimplifying?
`[Hackpact 3 - Write documentation & focus on the process of writing]`
Open the writing process and experiment collaborative practices for the documentation of the Workbook, a tool developed together with Supi to keep track and annotate configurations for different instruments and facilitate learning process.
Write the documentation together. Could there be multiple voices or is necessary to keep a single point of view? What does it mean to write with different intensities? Can we imagine ways to zoom in and out details level? How different knowledges can participate in this process?
`[Hackpact 4 - Write documentation & focus on the surrounding context]`
Set some references by looking back at the works made last year and read them through the axis of code and care. Or some other system of coordinates that suits better. Could the process of writing documentation reactivate old prototypes, or cast different light onto them?
Expand the research to tap into ongoing projects outside XPUB, such as freelance work and parallel research such as [Object Oriented Choreography](../ooc-summer-session/), that is an ongoing project of mine related to networked technologies, VR and contemporary dance.
Expand the research to tap into ongoing projects outside XPUB, such as freelance works and [parallel research](../ooc-summer-session/). Are there ways to make the documentation process more sustainable? Are there strategies to overcome a low-resources environment? What are the relations between documentation and the communities around a software?
Are there ways to make the documentation process more sustainable (socially, economically)? Are there strategies to overcome low-resources environments? Search for escamotages to create space and energies to document. Use documentation to work with collaborators, clients, and end-users and approach code from multiple point of view.
<!-- TODO: inflate this ^ -->
Try to infiltrate the industry of software development through documentation. Attempt to expose their public to these questions in subtle ways. Offer entry points and escape routes from the automatic outcomes proposed by tech solutionism.
`[hackpact 5 - Write documentation & focus on who is writing it]`
What are the relations between documentation and the community around a software?
- Experiment with versioning.
- Try to have several instances of the same documentation.
- Try to question who is writing and who is reading the documentation.
- Shift the moment in which the documentation happens.
- Where the documentation is hosted?
Question the nature of the documentation: what does it take for granted? For what kind of public it is produced, and what kind of public does it produce? How does it normalize the context around the software? What are its politics of access? How does it create entry points and how does it gatekeep?
Try to infiltrate the industry of software development through documentation. Attempt to expose their public to these questions in subtle ways. Offer entry points and escape routes from the universal solution proposed by big corporates.
`[hackpact 6 7 8 - Towards final project]`
<!-- TODO: this more concrete approach here -->
- Collect and organize the outcomes from the different hackpacts.
- Trace trends and synthetize common and diverting aspects.
- Research on a surface that could host this different facets.
### What is your timetable?
Is it a deck of cards? A table tennis setup with different prompts printed on different balls? Is it a game? A manifesto? A CMS? A trekking route or a 400km pilgrimage?
**October**
How can it inhabit the places where documentation is hosted?
Define a domain of research. Do not decide on it's granularity.
### What is your timetable?
Define the premises where which to ground the project by revisiting first year projects.
**October**
Think about a glossary and possible formats to test some concept in a small scale, such as the first public moment at Leeszal or the freelance works.
- Define a domain of research.
- Understand where to ground the project by revisiting first year prototypes.
Experiment writing the documentation for the [Padliography](https://hub.xpub.nl/soupboat/padliography/) and the [Workbook](https://hub.xpub.nl/soupboat/workbook/).
- Think about a glossary and possible formats to test some concept in a small scale, such as the first public moment at Leeszal.
<!-- TODO: provide some context about padliography and workbook -->
- Experiment writing the documentation for the [Padliography](https://hub.xpub.nl/soupboat/padliography/) and the [Workbook](https://hub.xpub.nl/soupboat/workbook/).
**November**
Work on OOC for December performance at NaO Festival, Milan. What does it mean to document a bespoke tool developed just for this project? Experiment with the documentation for the interactive patch of OOC.
Get in touch with key figures to interview for research.
- Experiment writing documentation for project outside XPUB, both artistic and commercial ones.
- Explore the moments in which the documentation happens.
**December**
OOC performance in Milan.
Follow-up about the different documentation processes.
Gather material to have an historical overview of software documentation.
- What does scientific literature have to say about software documentation?
- Archeology of software documentation. From printed manuals to README files to CD/CI websites.
**January**
Gather material to have a critical overview around software documentation.
Field research of the current state of software documentation. Explore different fields: big projects, small projects, corporate documentation and solo developers. Explore different languages and reflect on how they features are reflected in the documentation.
Experiment continuing writing the documentation for different prototypes. How does this process of writing documentation inform the process of writing the thesis?
Experiment with the idea of versioning, branching, collaborative writing.
- Field research of the current trends in software documentation. Explore different contexts (solo, coop, corporate, floss, proprietary) and different coding languages.
- Follow up on the outcomes of the different hackpacts. Focus on
1. materiality of the documentation (style, contents, forms),
2. context around the documentation (actors, timeframe, hosting)
**February**
Read read read and write write write.
Interview and case studies from different communities?
Experiment with the idea of versioning, branching, collaborative writing.
- Research and prototype possible formats for graduation project outcome. What surface could host this different factes together?
- 15 min daily prototypes starting from the sentence `A _________ to explore software documentation as a __________`
**March**
Self-induce dreams about the final outcome with a follow-up on the thesis research.
Research and prototype possible formats for graduation project outcome.
**April**
- Follow up on February daily prototypes
- **April**
Production!
Think about graduation exhibition and collective pubblication.
@ -121,19 +165,6 @@ Documenting software is a complex practice. Documenting software is a process of
As a piece of code would write: I am documented, therefore I am.
<!--
developement is really specific technical community (white cis male eheehhe)
a lot of violence, status quo, reinforced in the industr, competition,
control, frame the world in a form that you can control and act on from a really occidental point of view, colonialistic, extractive form
i would like to research on the question: can we do it in another way? giving back something and not only take
when you're using a tool you can learn the world throught the use of it, the difference is: can i use the scissors to cut a piece of paper and make a notebook or kill someone? -->
<!-- This is a list of current trends that the software industry enforces and naturalize.
With this project the intention is to situate my practice within ethical yet sustainable boundaries. -->
<!-- And viceversa. Undocumented software is invisible, but for the eyes of their own developers. And eventually, it begins to fade as soon as the developer looks away. -->
### Who can help you and how?
It would be interesting to get in touch with someone mantaining open source projects such as Paged.js, P5Js, vvvv.

@ -133,3 +133,5 @@ Developing togheter with others it's a way to renegotiate priorities when develo
[... staying low]
---
And viceversa. Undocumented software is invisible, but for the eyes of their own developers. And eventually, it begins to fade as soon as the developer looks away.

Binary file not shown.

After

Width:  |  Height:  |  Size: 115 KiB

@ -179,3 +179,66 @@ _some notes for the project:_
- Padliography category page on the wiki, with the same contents of the README.md and a list of the archives page.
- Now when the padliography initialize a new archive, it adds the `[[category: padliography]]` tag, in order to list all the active archives in the category page.
- Next step is: how to make it public?
### 17th Oct
Public event at Leeszaal: Gersande and me shared a table for discussing our intuitions with the public. It happened because G is working on the surface of the patent and I was super interested in drawing connections between that and the documentation. There were nice suggestions. Simon and Alice suggested to narrow down the audience, for example focusing on the use of documentation in the context of tech-coop. Need to have a look to the notes we collected through the ingenious carbon-copy notation system Grr and Kim developed.
After the event and the discussion Naami sent me this incredible screen that is going directly into the thesis
![Discord server fossil](discord.jpg)
Thank you Naami!
### 18th Oct
- Sent some memes to the Piet in order to make the Padliography public (namely: clumsy frog pictures that point to the wiki page of the documentation.
![frog 1](../padliography-2/Frog 01.jpg)
![frog 2](../padliography-2/Frog 02.jpg)
![frog 3](../padliography-2/Frog 03.jpg)
![frog 4](../padliography-2/Frog 04.jpg)
- Organize a public moment in PZI after the break. A monday morning session with the prototyping class? A Friday morning 1 hour worksiop / demo / user test?
### 25th Oct
- Prepare for the 31 Oct M&Ms
- Presentation and demo - 10 min
- Documentation read and review exercise - 10 min
- Mock product reviews???
- Roleplay like X_Kitchen (from kim & chae)
- Your character is a customer / reader of this documentation
- Mobile form with written feedback + something funny like product picture or reaction
- title, review, pro / cons + something like a call to participate to the documentation (such as explain the tool with your own words, or similar)
- Review form: could be interesting to link it to the contents of the documentation (as a way to send feedback to the ones writing the doc) (to create a channel of communication?)
-
- (simple form, store reviews in a small db, review different work ??? and an API to integrate the contents with real documentations)
- Think about the documentation for the Workbook with Supi. There is a draft strucutre here [workbook documentation](https://pad.xpub.nl/p/modcms_documentation).
- imagine it in a way to coexhist with the aforementioned api ???? wtf did i just wrote aforementioned for real
### M&Ms
- Presentation of the Padliography:
- Sorting table
- Filtering
- Add a new pad directly!! (m&ms)
- Init a new archive
- Add some pads (modcms, modcms_documentation)
- Switch between archives
- Documentation of the Padliography
- wiki
- 10 min roleplay writing exercise
- read + review as you were on trip advisor or amazon
- short review + stars ⭐

@ -0,0 +1,111 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Software documentation as a form of care???</title>
<link rel="stylesheet" href="style.css" />
</head>
<body>
<h1>The problem with <br />software documentation</h1>
<img src="trolley.jpg" alt="" srcset="" />
<p>
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.
</p>
<p>
To make software means not only to write code, but also to take a stance regarding this
trends. To make software means not only to write code, but also to create a context and
community around it.
</p>
<p>
Documentation is a space that interfaces the different actors around software. Software
documentation is a space with potential to renegotiate and reclaim given margins and
entry points. It is a chance to overwrite what is normalized, and let different
knowledges and voices participate in the discourse around software.
</p>
<p>
Documenting software is a complex practice. Documenting software is a process of
translation. Writing documentation it's more difficult than writing software itself. It
requires a lot of time and energy, and it involves many different skills: writing,
coding, knowing how to share and at which intensity. It's a collaborative practice that
could open to different voices.
</p>
<p>As a piece of code would write: I am documented, therefore I am.</p>
<p>
Coding is not just production of software, but also production of knowledge. A dialogue
between human and more-than-human actors. The guestlist of this conference of the bits
is often compiled by chance: the choice of a particular programming language, the coding
style, the development environment and ecosystem, the infrastructure that runs the code,
and so on, are the result of specific contingencies.
</p>
<p>
These contingencies are situated in precise contexts, and these contexts are different
one from another. Programming is not just sharing code, but sharing context. Programming
means to provide a point of view and a perspective to look at the world, before
attempting to get some grip onto it with a script. That's the reason why even if source
code, even when obfuscated, speaks for itself, it cannot always cast light around its
surroundings.
</p>
<p>
To make place for code turns to be a necessary act of care in the process of sharing
knowledge. 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.
</p>
<p>
Documentation is a way to produce narrations around software. To create a world for a
software to inhabit, to give it affordances and stretch what is possible to do or to
think with it. Documentation is a space for the political of software. It's a surface
that could host ideas in close contact with codes, letting them entangle and shape each
other.
</p>
<div class="pagebreak"></div>
<h1>The plan</h1>
<ul>
<li>
Focus on software documentation as an interface between code, users, developers,
communities, and the world.
</li>
<li>
Research how writing software documentation changes depending on the context and
actors involved.
</li>
<li>
Experiment with software documentation as a generative device to keep thinking
through code from different perspectives.
</li>
<li>
Explore software documentation as iterative process, as a format that grows and
shrinks through versioning and embrances branching to adapt to specific
environments.
</li>
<li>
Develop tools to facilitate rich software documentation. To assist and stimulate the
writing process with prompts and gently reminders that software documentation is a
form of care.
</li>
<li>
Question the nature of the documentation: what does it take for granted? For what
kind of public it is produced, and what kind of public does it produce? How does it
normalize the context around the software? What are its politics of access? How does
it create entry points and how does it gatekeep?
</li>
<li>
Try to infiltrate the industry of software development through documentation.
Attempt to expose their public to these questions in subtle ways. Offer entry points
and escape routes from the universal solution proposed by big corporates.
</li>
</ul>
</body>
</html>

Binary file not shown.

After

Width:  |  Height:  |  Size: 714 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 248 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 420 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 333 KiB

@ -1,8 +1,8 @@
---
categories:
- Utility
- Tool
- Pad
- Utility
- Tool
- Pad
cover: padtoles.jpg
cover_alt: a tadpole but with pad
date: 30/06/2022
@ -11,27 +11,114 @@ git: https://git.xpub.nl/kamo/pad-bis
slug: padliography-2
title: Padliography 2
url: /soupboat/padliography/
links:
- title: Wiki
url: https://pzwiki.wdka.nl/mediadesign/Category:Padliography
---
The Padliography is a tool to keep track of our pads. It is built to interact with the MediaWiki API, and it uses [XPUB & Lens-Based Wiki](https://pzwiki.wdka.nl/mediadesign/Main_Page)'s pages as archive.
A way to create, archive and retrieve our pads. Now with a fast way to insert new pads without too much effort uiii.
# Features
**Features:**
- Multiple archives
- Custom categories
- Filter by categories
- Table sorting
- Create new pad if URL is not provided
- Table Sorting
- Create new pad
- Interact with the wiki
## Quick Start
The Padliography homepage loads by default the XPUB2 archive. Just above the pads list it is indicated from where the pads are being fetched, and it is possible to change source by inserting the title of the page in which the other archive is.
To create a brand new archive click on `Init a new padliography` and insert a title and a short description to put in the wiki.
**Watch out:** This action will create a new blank page, so check that there is not already something with the same title in the wiki, or it will be overwritten. Thanks to the wiki's history, it is possible to recover overwritten contents, so the contents are not in total danger.
Use the **Add new pad** form to insert a pad in the archive. The required information are a title, the URL of the document, a short description, a date and some categories. The categories are custom, and are useful to organize pads in themes or context.
The **Filter Categories** section loads all the categories from the current archive and uses it to filter the list of pads.
The list of pads is sortable. Click on the headers to order the pad, click twice to invert the order.
At the moment this Padliography instance runs on the [Soupboat](https://hub.xpub.nl/soupboat/). If you are using it a lot or with a lot of pads, consider to install a new instance on a different environment, in order not to put a strain on the small Raspberry. It should be fine anyway.
## How does it work
To have an overview over the lifecycle of the Padliography let's start from the wiki.
The pads are stored in a page with a minimal template, such as the title, a short description and a section named Padliography with the archive. Here they are organized in a table that has the CSS class `padliography`.
Through the [MediaWiki API](https://pzwiki.wdka.nl/mediadesign/Special:ApiSandbox) we can request the contents of this page from somewhere else. This somewhere else is a small Raspberry Pi called Soupboat and installed on the 4th floor of the WdKA.
The Soupboat is a small server, and it runs a [Flask](https://flask.palletsprojects.com/en/2.2.x/) application that interacts with the wiki using the [mwclient](https://mwclient.readthedocs.io/en/latest/index.html) python library.
When a user enters the homepage of the padliography, the Flask application returns a [Vue3](https://vuejs.org/) app and through that requests to the wiki API the list of pads.
The response from the MediaWiki API is parsed on the server using [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/), that tries to find the `padliography` table with some CSS selectors and then builds a list of pads organized by the properties of the table's headers. The list of table is sent to the Vue app as JSON message, and used to compile a fancy sortable table and filtering system.
When a user interacts with the form to add a new pad the process is the same, but in the opposite direction: first the Vue app sends the data to the Flask application that in turns tries to add it in the archive wiki page.
## Development
### Local setup
To install the Padliography somewhere else start by cloning this repo.
```
git clone https://git.xpub.nl/kamo/pad-bis.git
```
Then move to the cloned repository folder and create a python virtual environment.
```
cd pad-bis
python3 -m venv venv
```
Activate the virtual environment
```
# on unix
source venv/bin/activate
# on windows
venv\Scripts\activate
```
and then install the requirements with pip. The **.** here refers to the current working directory, where the **setup.py** file can be found. There are specified all the packages the application needs.
```
pip install -e .
```
Once the installation is completed, launch the application and open it on the default port .
```
python pad-bis.py
```
If you open `localhost:5000` on your browser, it will return the padliography stuck in the loading process. This is why before interacting with the MediaWiki API we need to specify the credential for a user to log into the wiki. On your local version you can use your own credentials, but if you plan to put this padliography online it's better to use a dedicated user, aka a bot.
Remember not to commit your credentials on git, or they will be rendered public! Instead create and `.env` file, that will not be uploaded on git as specified in the `.gitignore` file.
Create an `.env` file in your working directory with the following properties:
```
MW_BOT= your username
MW_KEY= your password
```
At this step you are up and running, the padliography should be able to fetch the pad from the wiki etc.
<!-- TODO: put the padliography online -->
# TODO
<!-- ### Online configuration
- Setup script
- Search
- Server side rendering?
Going online depends on several variables, many of them being out of reach.
For this reason this section doesn't provide a comprehensive guide to put the project online, but just a reference to the configuration currently in use on the Soupboat.
-->
![lifecycle](https://git.xpub.nl/kamo/pad-bis/media/branch/master/lifecycle.jpg)
## License
_wip_ &
_Documentation coming soon_
This Padliography was distilled with the help and within the context of XPUB, 2022.
Copyleft with a difference: This is a collective work, you are invited to copy, distribute, and modify it under the terms of the [CC4r](https://constantvzw.org/wefts/cc4r.en.html).

@ -66,3 +66,36 @@ Some sketches for a new visual identity i've done before summer, but im not sure
![identity blu](identity.jpg)
![identity blu](identity2.jpg)
### aggregator: a different paradigm for note taking
I mean, a different paradigm at least for me.
Write each note in a different file and tag it.
Aggregate notes by tag or just sort them by date.
Interesting and easy to do.
It could be interesting to implement it!
From a technical point of view:
- things are stored in .md files
- static site generation? :^) in order to --> be more efficient and sustainable
- that means: whenever a git hook is called (such as every push), the server updates the list of contents.
- when a user requests the page, the server send the already rendered contents without building them on the fly
omg i hope this is what static site generation means bc im not sure
bonus: it could be done with a custom micro cms
the only thing i need are:
- text editor
- tag system
- file upload (for pictures, video, etc)
blurred documentation
### my page in the soupboat is getting slower
because there are a lot of contents! so probably should really generate the project list on the git hook, and then serve it directly

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

Loading…
Cancel
Save