diff --git a/bibliography.md b/bibliography.md index 9dfd2ec..31f2ca0 100644 --- a/bibliography.md +++ b/bibliography.md @@ -7,6 +7,9 @@ - Gabriel, R.P. (1998). Patterns of Software. Oxford University Press, USA. - 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/. + + TODO: https://ironicsans.substack.com/p/the-strangest-computer-manual-ever diff --git a/chapters/01_who_is_reading.md b/chapters/01_who_is_reading.md index b2291c2..5197c21 100644 --- a/chapters/01_who_is_reading.md +++ b/chapters/01_who_is_reading.md @@ -68,28 +68,34 @@ The same is true for the additional layers of reading~meaning necessary for a pr ## Welcoming writing -note: not sure about this separation below -- lowering barriers +The potential of documentation to orientate software in the world clashes against some big elephants in the room,and western tech culture should stop keep them in captivity. 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 a scarce resource. + +![discord rant](../img/discord.jpg) + +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 solve any problem in no time. + +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_ such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018). + +- far from being just a problem of SO +- embedded and encoded in technical culture +- read the f~ manual + +- encoded chauvinism +- embrace state of unknowing (ullman) ? +and from there to [list of references wip] + +- lowering barriers - debugging (p5.js education working group, 2015) - aesthetic programming - - readme examples? - multiple entry points - different entries make for different knowledges - - drawings and memes - welcome.js (bridle, 2016) -The potential of documentation to orientate software in the world clashes against some big elephants in the room,and western tech culture should stop keep them in captivity. 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 is 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 a scarce resource. - -It's ok, someone could object, every problem that can be asked on Stack Overflow, will eventually be asked in Stack Overflow (paraphrasing Atwood, 2007). - -and it's amazing to have communities that can solve every problems -but then ppl encoded chauvinism, toxic masculinity, ... - ## "Natural" reader - assuming a certain kind of reader - expert - dude diff --git a/img/discord.jpg b/img/discord.jpg new file mode 100644 index 0000000..e132714 Binary files /dev/null and b/img/discord.jpg differ