### What do you want to make?
## What do you want to make?
A list of devices to explore _software documentation_, that is the process of sharing knowledge and making worlds around software.
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.
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.
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.
Some elements of the list will relate to the materiality and surfaces where documentation is hosted,
<!-- which kind of approach with this materiality? -->
while others will be more entangled with the actors involved in the process.
<!-- again, which kind of approach? -->
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.
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.
_Software documentation_ is not just a list of technical procedures, but also a matter of providing context and orientate code 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.
_Software documentation_ is not just a list of technical procedures, but also a matter of providing context and orientate code 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.
<!-- what does it mean to re-enchant? -->
<!-- more about the fact that the list is open and just a starting point? -->
> "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]_
> "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]_
### Why do you want to make it?
## Why do you want to make it?
@ -35,28 +44,37 @@ This project grows out of the frustration of finding myself often trying to deal
At the same time, this very lack of documentation could be used as a starting point.
At the same time, this very lack of documentation could be used as a starting point.
<!-- more about concrete approach? could it be permacomputing? -->
<!-- rephrased as software as care? -->
<!-- care for who? other participant, dependencies, environment? -->
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 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.
<!-- more on who i would like to participate more -->
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. 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 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. A surface that could host ideas in close contact with code, letting them entangle and shape each other.
### How do you plan to make it?
## How do you plan to make it?
- Read software documentation
- Read software documentation
- (manuals, guides, references, tutorial)
- (manuals, guides, references, tutorial)
- (good ones, bad ones, ...)
- (good ones, bad ones, ...)
- Which software needs documentation? or
- Which software needs documentation?
- Wich documentation could use some rework?
- Which software do we want to document?
- Which software do we want to document?
<!-- ↑ should this be formulated more as a plan and less as a question? -->
- Prototype small systems to gather items for the list
- 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
- Tap into surrounding contexts
- Tap into surrounding contexts
- Meet the actors involved
- Meet the actors involved
- Gather impressions and insights
- Gather impressions and insights
- Order them in a list
- Host them in a list
- Leave it open for others to contribute
- Leave it open for others to contribute
- Find a support where to mount this list
- Find a support where to mount this list
### What is your timetable?
## What is your timetable?
- October
- October
- Define a domain of research.
- Define a domain of research.
@ -64,7 +82,7 @@ Documentation is a way to produce narrations around software. To create a world
- 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
- Experiment writing documentation for XPUB prototypes
- Experiment writing documentation for XPUB prototypes
- November
- November
- Experiment writing documentation for project outside XPUB
- Experiment writing documentation for projects outside XPUB
- Artistic and commercial ones.
- Artistic and commercial ones.
- Which software do we want to document?
- Which software do we want to document?
- December
- December
@ -87,23 +105,27 @@ Documentation is a way to produce narrations around software. To create a world
- First in the form of fast and iterative prototyping, then fine tuning and polishing.
- First in the form of fast and iterative prototyping, then fine tuning and polishing.
- Think about graduation exhibition and collective pubblication.
- Think about graduation exhibition and collective pubblication.
### Who can help you and how?
## Who can help you and how?
- people interested in the making of software
- people interested in the making of software
- people interested in the narrative around software
- critical code studies working group
- 100 rabbits
- permacomputing
### Relation to previous practice
## Relation to previous practice
I'm interested in the development of site-specific software. My artistic and design practice has always relied on the development of custom software to facilitate agency-on and comprehension-of complex systems. The tools themselves were never the main focus though, but rather just instruments to activate and be activated within particular contexts. Tools tailored to specific moments and then forgotten.
I'm interested in the development of site-specific software. My artistic and design practice has always relied on the development of custom software to facilitate agency-on and comprehension-of complex systems. The tools themselves were never the main focus though, but rather just instruments to activate and be activated within particular contexts. Tools tailored to specific moments and then forgotten.
During the first year at XPUB the approach started to change. Working together with my classmates let me realize the importance of sharing tools. To develop not just for yourself, but also for others. Code as common. How important it is to create a space for these tools to circulate, and how important are the narrations we build around these instruments. In this sense software development could be seen as a form of publishing.
During the first year at XPUB the approach started to change. Working together with my classmates let me realize the importance of sharing tools. To develop not just for yourself, but also for others. Code as a common. How important it is to create a space for these tools to circulate, and how important are the narrations we build around these instruments. In this sense software development could be seen as a form of care, as well as a form of publishing.
After the work in the past Special Issues, I'm trying to shift from compulsive development to susteinable development. Sustainable in relation to the context and the other actors involved in the process. This requires 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.
After the work in the past Special Issues, I'm trying to shift from compulsive development to susteinable development. Sustainable in relation to the context and the other actors involved in the process. This requires 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
## Relation to a larger context
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.
@ -119,7 +141,7 @@ These contingencies are situated in precise contexts, and these contexts are dif
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.
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.
@ -21,6 +21,7 @@ Key issues you want to explore (what research questions do these lead to?)
Please think of only 3 key issues.
Please think of only 3 key issues.
Once you identify these you can begin a chapter outline.
Once you identify these you can begin a chapter outline.
```
```
Discussion
Discussion
@ -29,7 +30,7 @@ Discussion
Software documentation
Software documentation
Programming software
Programming software
Sruggling a lot finding a surface between people that develop software, use software, communities concerned find a place that speaks/connects those different worlds
Struggling a lot finding a surface between people that develop software, use software, communities concerned find a place that speaks/connects those different worlds
User manual = documentation
User manual = documentation
@ -104,3 +105,17 @@ more zspecifically in the context of software programming
- value of documentation
- value of documentation
- documentation work is work
- documentation work is work
- economy of different knowledges
- economy of different knowledges
--- ok v2 ---
mode of address
- write with a mix of diverse registry, in order to have several layers of accessibility
- something that my parents, that are outside this bubble, could understand
- imagine the tone of a discussion around a technical manual: how can we make it more accessible? how can we make it more clear? some jokes not 100% related. technicalities. could it work for someone with a different background?
- imagine a list, so in a way both a linear and non-linear narration
- develop a writing machine for this. a specific way to write the thesis.
