@ -17,31 +17,21 @@ _note: I'm using the words toolkit, handbook, map, collection of tools, practice
### What do you want to make?
- 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_.
- An extensible toolkit to explore _software documentation_ as publishing surface.
- A 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_. How this exchange of resources could make place for different voices.
- 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 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.
- 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.
<!--- 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.
How this exchange of resources could make place for different voices. How writing _software documentation_ changes depending on the context and actors involved? -->
- A writing machine to build world around software.
### How do you plan to make it?
_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._
_The different directions are: materiality of software documentation, actors of software documentation, economy of software documentation_
`[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.
@ -52,23 +42,23 @@ Where does software documentation begin and where does it end? What about README
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_.
As initial case study focus on the [Padliography](https://hub.xpub.nl/soupboat/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?
What does it mean to offer it to someone else? How to talk the same language in 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.
Open the writing process and experiment collaborative practices for the documentation of the [Workbook](https://hub.xpub.nl/soupboat/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?
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 the process?
`[Hackpact 4 - Write documentation & focus on the surrounding context]`
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 work and parallel research like [Object Oriented Choreography](../ooc-summer-session/), a performative project of mine related to networked technologies, VR and contemporary dance.
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.
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.
Try to infiltrate the industry of software development through documentation. Attempt to expose their public to these issues in subtle ways. Offer entry points and escape routes from the automatic outcomes proposed by tech solutionism. Offer alternatives to sedimented roles in the care of software.
`[hackpact 5 - Write documentation & focus on who is writing it]`
@ -76,7 +66,7 @@ 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.
- Try to question who gets to write and who gets to read the documentation.
- Shift the moment in which the documentation happens.
- Where the documentation is hosted?
@ -86,11 +76,8 @@ Question the nature of the documentation: what does it take for granted? For wha
- 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.
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?
How can it inhabit the places where documentation is hosted?
- Research for a surface that could host this different facets.
- How can it inhabit the usual places where documentation is hosted?
### What is your timetable?
@ -124,19 +111,20 @@ How can it inhabit the places where documentation is hosted?
**February**
- 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 __________`
- 15 min daily prototypes starting from the sentence `A _________ to explore software documentation as a _________`
**March**
- Follow up on February daily prototypes
- **April**
- Follow up on February daily prototypes and plan for production.
Production!
**April**
Production! In the form of fast and iterative prototyping.
Think about graduation exhibition and collective pubblication.
**May**
Production!
Production! In the form of fine tuning and polishing.
Think about graduation exhibition and collective pubblication.
**June**
@ -167,7 +155,7 @@ As a piece of code would write: I am documented, therefore I am.
### 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.
It would be interesting to get in touch with someone mantaining the documentation of open source projects.
Some interesting things could emerge from field research directly in git repositories, issues and wikis.
### Relation to previous practice
@ -180,6 +168,11 @@ After the work in the past special issues, I'm trying to shift from developing c
### Relation to a larger context
- 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.
> Code is always addressed to someone. [...] We do not write code for our computers, but rather we write it for humans to read and use. [Jesse Li (2020)](https://blog.jse.li/posts/software/)
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.
