@ -33,8 +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" could also 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.
@ -44,10 +43,6 @@ For example [Vue.js](https://vuejs.org/guide/essentials/lifecycle.html#lifecycle
The introduction to a program situates it also within a larger ecosystem: how to install it, and what dependencies it requires to work properly. As Geoff Cox and Winnie Soon elaborate on their decision of a downloadable code editor instead of a web one for their classes, code is more than just a single piece of software. It is also the relations with the configuration of one's own computer and operating system. (Cox and Soon, 2020)
The introduction to a program situates it also within a larger ecosystem: how to install it, and what dependencies it requires to work properly. As Geoff Cox and Winnie Soon elaborate on their decision of a downloadable code editor instead of a web one for their classes, code is more than just a single piece of software. It is also the relations with the configuration of one's own computer and operating system. (Cox and Soon, 2020)
```
better transition above better conclusion below
```
The initial imprinting of documentation is a vantage point to orientate code in the world.
The initial imprinting of documentation is a vantage point to orientate code in the world.
## A code companion
## A code companion
@ -70,36 +65,24 @@ The same is true for the additional layers of reading~meaning necessary for a pr
The potential of documentation to orientate software in the world clashes against some big elephants in the room, and tech culture should stop keep them in captivity. Sure, it would be nice if developers could rely on several kinds of documentation when approaching code. Unfortunately often there is not even one available.
The potential of documentation to orientate software in the world clashes against some big elephants in the room, and tech culture should stop keep them in captivity. Sure, it would be nice if developers could rely on several kinds of documentation when approaching code. Unfortunately often there is not even one available.
Writing documentation is demanding. It's more delicate than programming, and require a whole set of skills usually not treasured by the dev community. `(sorry this maybe was an overstatement, hope it is)`A kind of emotional intelligence and sensitivity far to be found in the competitive wastelands of the IT industry. Here no one wants to write documentation, nor hire someone to do it (Gabriel, 1996). As a result, in a world where software thrive, documentation still seems to be a scarce resource.
Writing documentation is demanding. It's more delicate than programming, and require a whole set of skills usually not treasured by the dev community. A kind of emotional intelligence and sensitivity far to be found in the competitive wastelands of the IT industry. Here no one wants to write documentation, nor hire someone to do it (Gabriel, 1996). As a result, in a world where software thrives, documentation still seems to be a scarce resource.
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.
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 shared effort, together with the endless mailing lists, forums, discord servers and dedicated sources for whatever topic. It's astonishing how online communities 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)`
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)
`not sure machism is the right word here`
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 space felt unfriendly for _outsiders_, such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018).
Far from being just a Stack Overflow problem, machism is deeply embedded in the IT discourse, soaking through technical writings as well.
For years there have been discussions on the platform about tone. At the question _"Should 'Hi', 'thanks', taglines, and salutations be removed from posts?"_, one of the founders of Stack replied with a [RegEx](https://meta.stackexchange.com/a/93989) to filter automagically what some of the experienced users perceived as noise. This _regular expression_, a way to target specific text patterns in programming, started then to be silently applied to every query sent to the website, trimming out etiquette and leaving just technicalities.
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.
Far from being just an isolated problem, this crudity is deeply embedded in the IT discourse, soaking through technical writings as well. 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.
_Real programmers_ read the fucking manual.
_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)
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)
