_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?
- An extensible toolkit to explore the ecology of _software documentation_: its materiality, the actors involved and the economy that surrounds it.
This project will compile a list of devices to explore _software documentation_, that is the process of sharing knowledge and making worlds around software.
- A set of tools and practices that focus on _software documentation_ as an interface between the code, the user, the developer, the community, and the world.
These devices will be of various nature: tools, thoughts, anecdotes, excercises, prompts, secrets, ... They will offer entry points to articulate _software documentation_ as a form of care.
- 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.
Some elements of the list will relate to the materiality and the surfaces where documentation is hosted, while others will be more entangled with the actors involved in the process.
---
To work within the constraints of a structure such as the list will help to think through the complexity of the topic. This complexity will be preserved and encoded in the relations between different elements.
_Software documentation_ is not just a list of technical procedures, but also a matter of providing context and orientate the software in the world. In the same way I want to facilitate a space where to weave together multiple voices and different registry.
<!-- - An extensible toolkit to explore the ecology of_software documentation_: its materiality, the actors involved and the economy that surrounds it. -->
- A collection of small devices to assist and stimulate the documentation process, with cue and gently reminders that _software documentation_ is a form of care.
<!-- - A set of tools and practices that focus on_software documentation_ as an interface between the code, the user, the developer, the community, and the world. -->
- A series of writing prompts to experiment with _software documentation_ as a generative device to keep thinking through code from different and marginal perspectives.
<!-- - 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 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 collection of small devices to assist and stimulate the documentation process, with cue and gently reminders that_software documentation_ is a form of care. -->
- A (loose, habitable, extensible) map to orientate around what does it mean to _make software_ besides just writing code.
<!-- - A series of writing prompts to experiment with_software documentation_ as a generative device to keep thinking through code from different and marginal perspectives. -->
- A writing machine to build worlds around software.
<!--- 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. -->
<!--- A writing machine to build worlds 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._
- Define a domain of research
- Write software documentation
- Experiment with contents, tone and style
- Focus on the writing process
- Explore surrounding context
- Understand the actors involved
<!-- 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]`
<!-- `[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.
<!--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.-->
`[Hackpact 2 - Write documentation & focus on its contents and style]`
<!-- `[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?
<!--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](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_.
<!-- 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 in 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]`
<!-- `[Hackpact 3 - Write documentation & focus on the process of writing]` -->
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.
<!-- 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 the 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]`
