- Fuller, M., ed. (2008). Software studies a lexicon. Cambridge, Massachusetts Mit Press.
- Fuller, M., ed. (2008). Software studies a lexicon. Cambridge, Massachusetts Mit Press.
- Gabriel, R.P. (1998). Patterns of Software. Oxford University Press, USA.
- Gabriel, R.P. (1998). Patterns of Software. Oxford University Press, USA.
- A Wishlist for Trans\*femminist Servers. 2022. https://etherpad.mur.at/p/tfs
- A Wishlist for Trans\*femminist Servers. 2022. https://etherpad.mur.at/p/tfs
- Hanlon, J. (2018). Stack Overflow Isn’t Very Welcoming. It’s Time for That to Change. [online] Stack Overflow Blog. Available at: https://stackoverflow.blog/2018/04/26/stack-overflow-isnt-very-welcoming-its-time-for-that-to-change/.
- Hanlon, J. (2018). Stack Overflow Isn’t Very Welcoming. It’s Time for That to Change. [online] Stack Overflow Blog. Available at: https://stackoverflow.blog/2018/04/26/stack-overflow-isnt-very-welcoming-its-time-for-that-to-change/.
- how to quote propperly an introduction from a book series? (software studies)
- how to quote propperly an introduction from a book series? (software studies)
- find where to put _code documentation_&_developers_ paragraphs
- find where to put _code documentation_&_developers_ paragraphs
---
---
@ -27,26 +27,23 @@ The first chapter focuses on documentation as publishing surface. Who's reading,
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. It reaches not only beginners, but experienced programmers as well. It affects thinking about software continuously, and from different perspectives.
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. It reaches not only beginners, but experienced programmers as well. It affects thinking about software continuously, and from different perspectives.
The second part frames documentation as a crossroads, where different knowledges meet in the making of software.
The second part frames documentation as 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.
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 third section is focused on worlding, and the relation between code, documentation practices and political aesthetic.
The third 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)
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)
## Software documentation
## Software 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.
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 perspective of this thesis is more aligned to the docs for [ImageMagick](https://imagemagick.org/script/command-line-processing.php), than to the ones for [GIMP](https://www.gimp.org/docs/).
The perspective of this thesis is more aligned to the docs for [ImageMagick](https://imagemagick.org/script/command-line-processing.php), than to the ones for [GIMP](https://www.gimp.org/docs/).
## For developers
## For developers
Another term to dismantle here is _developer_.
Another term to democratize 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 it is 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 it is 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.
`potential caption for image`
`potential caption for image`
_Who is a developer? One who programs for a living or one who lives for programming? (based)_
_Who is a developer? One who programs for a living or one who lives for programming? (based)_
@ -33,6 +33,7 @@ again versioning tiger ding sun ? --> https://tdingsun.github.io/worlding/
(did already here --> https://hub.xpub.nl/soupboat/~kamo/projects/api-worldbuilding/ )
(did already here --> https://hub.xpub.nl/soupboat/~kamo/projects/api-worldbuilding/ )
## Getting started
## Getting started
`(Getting Startled also could make for a nice title)`
`(Getting Startled also could make for a nice title)`
Reading undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective. It is often the first thing one gets across when approaching a new library or programming language, and it shapes the way a developer thinks about particular piece of code.
Reading undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective. It is often the first thing one gets across when approaching a new library or programming language, and it shapes the way a developer thinks about particular piece of code.
@ -73,31 +74,38 @@ Writing documentation is demanding. It's more delicate than programming, and req
It's ok, someone could argue, every question that can be asked on Stack Overflow, will eventually be asked in Stack Overflow (versioning Atwood, 2007). The popular Q&A website for developers is just an example of digital knowledge as a common, and it's astonishing to have online communities that can tackle on any problem in no time.
It's ok, someone could argue, every question that can be asked on Stack Overflow, will eventually be asked in Stack Overflow (versioning Atwood, 2007). The popular Q&A website for developers is just an example of digital knowledge as a common, together with the endless mailing lists, forums, discord servers and dedicated sources for whatever topic. It's astonishing to have online communities that can tackle on any problem in no time.
But it's not rare for these places to feel unwelcoming, or even hostile. In 2018, Stack Overflow publicly admitted that there was a problem concerning their userbase. The platform felt unfriendly for _outsiders_ (what a choice of words) such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018).
`add what they did to address the issue (or did not)`
But it's not rare for these places to feel unwelcoming, or even hostile. In 2018, Stack Overflow pubblicly admitted that there was a problem concerning their userbase. The platform felt unfriendly for _outsiders_ (what a choice of words) such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018).
the very founder of Stack Jeff Atwood came up with a [ridiculous RegEx to remove salutations from questions in SO](https://meta.stackexchange.com/a/93989)
Far from being just a Stack Overflow problem, machism is deeply embedded in the IT discourse, soaking through technical writings as well.
`not sure machism is the right word here`
The denigrating expressions of superiority in matters concerning programming that Marino calls _encoded chauvinism_ (Marino, 2020) constitute the main ingredient in the brew of toxic geek masculinity. Real programmers don't use this code editor. Real programmers don't use this programming language. Real programmers don't care about others feelings. Real programmers read the fucking manual. Etc.
Far from being just a Stack Overflow problem, machism is deeply embedded in the IT discourse, soaking through technical writings as well.
Ellen Ullman accounts on the emotional dumbness of her male collegues give an insight of a problematic behavior first intercepted and then capitalized by the IT industry (Ullman, 1997; 2017).
The denigrating expressions of superiority in matters concerning programming that Marino calls _encoded chauvinism_ (Marino, 2020) constitute the main ingredient in the brew of toxic geek masculinity. _Real programmers_ don't use this code editor. _Real programmers_ don't use this programming language. _Real programmers_ don't care about others feelings. Etc.
`--> RTFM etc, but strange transition ?`
_Real programmers_ read the fucking manual.
`--> RTFM small paragraph ?`
Ellen Ullman accounts on the emotional dumbness of her _real programmers_ colleagues give an insight of a problematic behavior, first intercepted and then capitalized by the IT industry. "In meetings, they behave like children. They tell each other to shut up. The call each other idiots. They throw balled-up paper. One day, a team member screams at his Korean colleague, 'Speak English!' (A moment of silence follow this outburst, at least.)" (Ullman, 1997; 2017)
