How to create entry points for more people to participate to programming practices?
```
How to facilitate more diverse communities around coding?
How to acknowledge the value of different perspectives in the making of software?
Code documentation seems to be a crossroads where different knowledges meet in the making of software. A space that interfaces between the code, the user, the developer, and the world. A space where to welcome different voices: not just engineers, not just experts, not just dudes. A space where to acknowledge the massive labor of care besides technicalities, often marginalized by coding culture.
### Two flows
There are two flows around code documentation:
There are two flows around code documentation:
@ -16,9 +22,9 @@ Documentation as a backdoor where to inject political aesthetic into software: t
This research explores these two currents, with the thesis that code documentation is an ideal publishing surface to create worlds around software, and to orientate software in the world.
This research explores these two currents, with the thesis that code documentation is an ideal publishing surface to create worlds around software, and to orientate software in the world.
The first flow seems nothing new, just the nature of every kind of technical documentation. To encode and filter knowledge, and ultimately to share it with others. Here documentation stands at a vantage point: by reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives. Although, in order to make use of this sweet spot several issues need to be raised: documentation often doesn't feel welcoming for programmers others than dudes. Code documentation is still very gendered, and makes a lot of assumptions about who's reading. Addressing the problems of who is reading means also to aknowledge the counterpart of who is writing. Reading code documentation highlights that the making software does not stop with coding: that there is a massive labor of care besides engineering headaches, and that is valuable as much as technical contribuitions.
The first flow seems nothing new but the nature of every kind of technical documentation. To encode and filter knowledge, and ultimately to share it with others. Here documentation stands at a vantage point: by reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives. Although, in order to make use of this sweet spot several issues need to be raised: documentation often doesn't feel welcoming for programmers others than dudes. Code documentation is still very gendered, and makes a lot of assumptions about who's reading. Addressing the problems of who is reading means also to acknowledge the counterpart of who is writing. Reading code documentation highlights that the making software does not stop with coding: that there is a massive labor of care besides engineering headaches, and that is valuable as much as technical contributions.
The second one is more labile and subtle: it deals with softer things than software. With political choices that inform technical details, with code close to codes of conduct, with power dynamics and forms of exclusion in the making of software. It is slippery matter, practiced with a range of different approaches, such as reclaiming spaces, re-enchanting tools and reassuring others.
The second one is more labile and subtle: it deals with softer things than software. With political choices that inform technical details, with code close to codes of conduct, with power dynamics and forms of exclusion in the making of software. It is slippery matter, practiced with a range of different approaches, such as reclaiming spaces, enchanting tools and reassuring others.
```placeholder
```placeholder
And these different techniques will be addressed in the second part of the thesis.
And these different techniques will be addressed in the second part of the thesis.
@ -49,13 +55,13 @@ A way to situate programming in specific contexts.
The concepts of worlding, political aesthetic, and critical thinking can be applied to all sorts of technical manuals. However, the approaches and methods explored in this thesis are mostly informed by practices related to code documentation. While reading, please bind the terms software, application, program, etc. to code. Software documentation? Code documentation.
The concepts of worlding, political aesthetic, and critical thinking can be applied to all sorts of technical manuals. However, the approaches and methods explored in this thesis are mostly informed by practices related to code documentation. While reading, please bind the terms software, application, program, etc. to code. Software documentation? Code documentation.
```placeholder
```placeholder
Some examples of documentation, different types and intensieties
Some examples of documentation, different types and intensities
```
```
Another term to contextualize (and dismantle?) here is _developer_.
Another term to contextualize (and dismantle?) here is _developer_.
By stripping down every trace of professionalism and formal education, let's agree that a developer is someone who tinkers with code. No matter at which level, nor distance, nor experience. No matter if for work, for fun, for study. No matter if one is actively involved in the development of a tool, or comes from the user perspective. Ellen Ulman writes that programming is a disease, but the situation is even worse: code is contagious material, touch it once and you are a developer.
By stripping down every trace of professionalism and formal education, let's agree that a developer is someone who tinkers with code. No matter at which level, nor distance, nor experience. No matter if for work, for fun, for study. No matter if one is actively involved in the development of a tool, or comes from the user perspective. Ellen Ullman writes that programming is a disease, but the situation is even worse: code is contagious material, touch it once and you are a developer.
```note
```note
Next three paragraphs are to readjust a bit after the new structure: chapters 1 and 2 are merged and are a first part about entry points.
Next three paragraphs are to readjust a bit after the new structure: chapters 1 and 2 are merged and are a first part about entry points.
@ -63,6 +69,6 @@ Next three paragraphs are to readjust a bit after the new structure: chapters 1
This thesis explores code documentation as a publishing surface.
This thesis explores code documentation as a publishing surface.
The first part focuses on who is reading, who is addressed, and who is left out. Documentation brings an understanding on software by disclosing its magic. It reveals what can be done with it, and where are the limits. By lowering barriers and creating entry points, documentation broadens participation. By reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives. Documentation is a crossroads, where different knowledges meet in the making of software. Documentation is a space that interfaces between the code, the user, the developer, and the world. A space where to welcome different voices: not just engineers, not just experts, not just dudes. A space to acknowledge the massive labor of care besides technicalities, often marginalized by coding culture.
The first part focuses on who is reading, who is addressed, and who is left out. Code documentation brings an understanding on software by disclosing its magic. It reveals what can be done with it, and where are the limits. By lowering barriers and creating entry points, documentation broadens participation. By reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives.
The second section is focused on worlding, and the relation between code, documentation practices and political aesthetic. Here documentation is seen as a surface that could host principles in close contact with algorithms, letting them entangle and shape each other. A way to orientate our instruments towards "non-extractive relationships, but in the meantime, being accountable for the ones they are complicit with." (A Wishlist for Trans\*feminist Servers, 2022)
The second section is focused on worlding, and the relation between code, documentation practices and political aesthetic. Here documentation is seen as a surface that could host principles in close contact with algorithms, letting them entangle and shape each other. A way to orientate our instruments towards "non-extractive relationships, but in the meantime, being accountable for the ones they are complicit with." (A Wishlist for Trans\*feminist Servers, 2022)
