This project will compile a list of devices to explore _software documentation_, that is the process of sharing knowledge and making worlds around software.
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 list of devices to explore _software documentation_, that is the process of sharing knowledge and making worlds around software.
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.
These instruments 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.
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.
Some elements of the list will relate to the materiality and surfaces where documentation is hosted, while others will be more entangled with the actors involved in the process.
_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.
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 hopefully be preserved and encoded in the relations between different items.
<!-- - An extensible toolkit to explore the ecology of_software documentation_: its materiality, the actors involved and the economy that surrounds it. -->
_Software documentation_ is not just a list of technical procedures, but also a matter of providing context and orientate software in the world. In the same way, the list is meant to be a texture where to weave together multiple voices and diverse registry, in order to re-enchant the making of 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. -->
<!-- - 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 cue and gently reminders that_software documentation_ is a form of care. -->
<!-- - 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 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?
### How do you plan to make it?
- Define a domain of research
- Read software documentation
- (manuals, guides, references, tutorial)
- Write software documentation
- Write software documentation
- Experiment with contents, tone and style
- Experiment with contents, tone and style
- Focus on the writing process
- Focus on the writing process
- Explore surrounding context
- Tap into surrounding context
- Understand the actors involved
- Meet the actors involved
- Gather impressions and insights
<!-- 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. -->
- Order them in a list
- Leave it open for others to contribute
<!-- `[Hackpact 1 - Define a domain of research]` -->
- Find a support where to mount this list
<!-- 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]` -->
<!-- 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_. -->
<!-- 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](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? -->
`[Hackpact 4 - Write documentation & focus on the surrounding context]`
_"A list doesn't have to impose a single mode of ordering on what is included in it. Items in the list aren't necessarily responses to the same questions but may hang together in other ways... a list differs from a classification in that it recognizes its incopleteness. It doesn't even need to seek completeness. If someone comes along with something to add to the list, something that emerges as important, this may indeed be added to it."_
[John Law and Annemarie Mol, Complexities: Social Studies of Knowledge Practices]
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 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]`
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 gets to write and who gets to read 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?
`[hackpact 6 7 8 - Towards final project]`
- Collect and organize the outcomes from the different hackpacts.
- Trace trends and synthetize common and diverting aspects.
- 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?
### What is your timetable?
**October**
- October
- Define a domain of research.
- Define a domain of research.
- Understand where to ground the project by revisiting first year prototypes.
- Understand where to ground the project by revisiting first year prototypes.
- Think about a glossary and possible formats to test some concept in a small scale
- Think about a glossary and possible formats to test some concept in a small scale, such as the first public moment at Leeszal.
- Experiment writing documentation for XPUB prototypes
- November
- Experiment writing the documentation for the [Padliography](https://hub.xpub.nl/soupboat/padliography/) and the [Workbook](https://hub.xpub.nl/soupboat/workbook/).
- Experiment writing documentation for project outside XPUB
- Artistic and commercial ones.
**November**
- Focus on the moments when the documentation happens.
- December
- Experiment writing documentation for project outside XPUB, both artistic and commercial ones.
- Archeology of software documentation.
- Explore the moments in which the documentation happens.
- Field research of the current trends in software documentation.
- Explore different contexts and different coding languages.
**December**
- January
- 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**
- 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
- Follow up on the outcomes of the different hackpacts. Focus on
1. materiality of the documentation (style, contents, forms),
1. materiality of the documentation (style, contents, forms),
2. context around the documentation (actors, timeframe, hosting)
2. context around the documentation (actors, timeframe, hosting)
- February
**February**
- Research possible formats for the project outcome.
- What surface could host this different factes together?
- Research and prototype possible formats for graduation project outcome. What surface could host this different factes together?
- Fast daily prototypes
- 15 min daily prototypes starting from the sentence `A _________ to explore software documentation as a _________`
- March
**March**
- Follow up on February daily prototypes and plan for production.
- Follow up on February daily prototypes and plan for production.
- April
- Production!
- First in the form of fast and iterative prototyping, then fine tuning and polishing.
- Think about graduation exhibition and collective pubblication.
**April**
### Why do you want to make it?
Production! In the form of fast and iterative prototyping.
This project grows out of the frustration of finding myself often trying to deal with bad documented pieces of software. While for sure there is some thrill in understanding how to stitch together these codes, the lack of documentation poses a great hindrance for the participation of diverse knowledges in the making of software.
Think about graduation exhibition and collective pubblication.
**May**
### Who can help you and how?
Production! In the form of fine tuning and polishing.
### Relation to previous practice
Think about graduation exhibition and collective pubblication.
**June**
Graduation exhibition.
I'm interested in the development of site-specific software, that is codes that emerge from a community. In this perspective imagine coding as a form of care. Programming as a way to facilitate agency-on and comprehension-of complex systems.
Party
**July**
After the work in the past special issues, I'm trying to shift from developing compulsivly to developing in a meaningful way. Meaningful especially in relation to the environment and the other people involved in the process. This means to learn how to balance between different priorities, to understand when to develop something from scratch and when to participate into already existing discourses. It means to learn how to balance between accessibility, susteinability and flexibility.
Siesta
### Relation to a larger context
### Why do you want to make it?
Software comes from a really specific occidental cultural tradition.
Software comes from a really specific occidental cultural tradition.
Software tends to priviledge masculine, binary, exploitative and extractive practices.
Software tends to priviledge masculine, binary, exploitative and extractive practices.
@ -163,49 +99,13 @@ Software comes invisible, transparent, neutral.
Software models the world in order to control it.
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.
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.
To make software means not only to write code, but also to create a context around.
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.
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.
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 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
> The ordinary professional programmer addresses himself to the problem to be solved, whereas the compulsive programmer sees the problem mainly as an opportunity to interact with the computer. (Joseph Weizenbaum)
I'm into the development of site-specific software. Codes that inhabit and interact with a community. Coding as a form of care. Programming as a way to facilitate agency-on and comprehension-of complex systems. I'm trying to learn how to approach complexity as an environment. How a work can be complex without forcing the result being complicated. This usually happens when diverse actors participate in a process, when ideas and practices traverse through the software without being totally framed into it.
After the work in the past special issues, I'm trying to shift from developing compulsivly to developing in a meaningful way. Meaningful especially in relation to the environment and the other people involved in the process. This means to learn how to balance between different priorities, to understand when to develop something from scratch and when to participate into already existing discourses. It means to learn how to balance between accessibility, susteinability and flexibility.
### 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.
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.
> If software illuminates an unknown, it does so through an unknowable (software) ([Wendy Hui Kyong Chun](http://computationalculture.net/software-studies-revisited/), 2022)
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.
> “Our machines should be non-binary, decentralized and unknowing.” (James Bridle. “Ways of Being.”)
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 diverse knowledges and voices participate in the discourse that is software.
> “To think again or anew, we need to re-enchant our tools.” (James Bridle. “New Dark Age.”)
Documentation is a way to produce narrations around software. To create a world for the code 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 in the software. It's a surface that could host ideas in close contact with code, letting them entangle and shape each other.
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.
Documenting software is a complex practice. It is a process of translation. It requires a lot of time and energy, and it involves many different skills: writing, coding, knowing how to share informations and at which intensity. It is a collaborative practice, an economy of different contributions, a way to let others know where does some code come from, and where it would like to go.
To situate _software documentation_ as an interface between the code, the user, the developer, and the world, is a way to focus on the economy of different knowledges that is necessary when it comes to making software.
_"A list doesn't have to impose a single mode of ordering on what is included in it. Items in the list aren't necessarily responses to the same questions but may hang together in other ways... a list differs from a classification in that it recognizes its incopleteness. It doesn't even need to seek completeness. If someone comes along with something to add to the list, something that emerges as important, this may indeed be added to it."_
[John Law and Annemarie Mol, Complexities: Social Studies of Knowledge Practices]
@ -135,3 +135,98 @@ Developing togheter with others it's a way to renegotiate priorities when develo
---
---
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.
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.
---
As a piece of code would write: I am documented, therefore I am.
## Coding Contingencies
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.
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.
> If software illuminates an unknown, it does so through an unknowable (software) ([Wendy Hui Kyong Chun](http://computationalculture.net/software-studies-revisited/), 2022)
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.
> “Our machines should be non-binary, decentralized and unknowing.” (James Bridle. “Ways of Being.”)
> “To think again or anew, we need to re-enchant our tools.” (James Bridle. “New Dark Age.”)
> The ordinary professional programmer addresses himself to the problem to be solved, whereas the compulsive programmer sees the problem mainly as an opportunity to interact with the computer. (Joseph Weizenbaum)
> 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/)
## Brainstorming fr the projekt
- An extensible toolkit to explore the ecology of _software documentation_: its materiality, the actors involved and the economy that surrounds it.
- 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 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 cue and gently reminders that _software documentation_ is a form of care.
- 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 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.
---
## About the hackpacts
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.
`[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](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?
`[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.
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 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 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]`
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 gets to write and who gets to read 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?
`[hackpact 6 7 8 - Towards final project]`
- Collect and organize the outcomes from the different hackpacts.
- Trace trends and synthetize common and diverting aspects.
- Research for a surface that could host this different facets.
- How can it inhabit the usual places where documentation is hosted?
---
I'm trying to learn how to approach complexity as an environment. How to stay complex without forcing the result being complicated, that is how to reduce complexity without loosing value. This usually happens when diverse actors participate in the process, when ideas and practices traverse through the software without being totally framed into it.
