diff --git a/chapters/00_intro.md b/chapters/00_intro.md index 11e76a7..781cf91 100644 --- a/chapters/00_intro.md +++ b/chapters/00_intro.md @@ -1,11 +1,12 @@ TODO: -- groud with a concrete example to make the intro more accessible -- adjust contingencies paragraph to better address intended audience -- scheme is: - - Lowering barriers. - - Welcoming diverse knowledges. - - Orientate software in the world. +- groud with a concrete example +- adjust second paragraph to better address audience +- rephrase quotes ? +- outline is: + - Lowering barriers to + - Welcoming diverse knowledges for + - Orientate software in the world --- @@ -21,11 +22,12 @@ It's an approach that helps us to think about software as a cultural object. Som An object that, in turn, can be used to probe its surroundings. Who is developing? Who is gonna use it? Who is paying for it and why? How is it structured? It is a big and centralized system or a loose collection of small and interchangable tools? How long is it supposed to last? How can be fixed if it breaks? -The main focus of this research is to explore software documentation as a surface where this kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source. +The main focus of this research is to explore software documentation as surface where this kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source. + +A way to situate programming in specific contexts. 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. -Documentation is a public 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 aknowledge 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 aknowledge the massive labor of care besides technicalities, often marginalized by coding culture. 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) diff --git a/chapters/01_interface.md b/chapters/01_interface.md deleted file mode 100644 index f69b71d..0000000 --- a/chapters/01_interface.md +++ /dev/null @@ -1,5 +0,0 @@ -_can documentation be an interface between different knowledges?_ - -- interface between code, developer, world -- post meritocracy manifesto -- trans\*femminist server whishlist diff --git a/chapters/01_lowering_barriers.md b/chapters/01_lowering_barriers.md new file mode 100644 index 0000000..3fb64fe --- /dev/null +++ b/chapters/01_lowering_barriers.md @@ -0,0 +1,45 @@ +# Who is reading? + +- software documentation + + - which software (code related, situated software) + - which documentation (from framework to form of care) + - references: + - diataxis (procida, 2017) + - situated software (shirky, 2004) + +Documentation comes in many different forms. Daniele Procida offers a systematic approach to organize this wealth of formats (diataxis.fr, 2017). His framework is built at the intersection of two axis: one goes from theoretical to practical knowledges, while the other from study to work. Here _study_ could be read as _learning_ or _understanding_, while _working_ means getting things done. Another powerful couple of synonims is _receiving_ and _giving_: by combining the renamed axis we can get a glimpse of the flow of knoweldge involved in documentation. + + + +``` +practice receiving tutorial +theory receiving explanation +practice giving how to +theory giving reference +``` + +The structure of dyataxis is useful to navigate through the different needs of a reader, or through different readers at all. So who's reading? + +- who's reading? + + - assuming a certain kind of reader + + - expert + - dude + + - references: + - programming for the millions (ullman, 2016) + - read the feminist manual (karayanni, 2021 ) + +- lowering barriers + + - Problems with depth (too shallow or too deep) + - Where to start? + - references: + - welcome.js (bridle, 2016) + - debugging (p5.js education working group, 2015) + +- multiple entry points + - different entries make for different knowledges + - drawings and memes diff --git a/chapters/02_economy.md b/chapters/02_welcoming_others.md similarity index 77% rename from chapters/02_economy.md rename to chapters/02_welcoming_others.md index 8c76a20..fe7890c 100644 --- a/chapters/02_economy.md +++ b/chapters/02_welcoming_others.md @@ -1,4 +1,11 @@ -_can documentation trigger different kinds of economy around software?_ +# Who is writing? + +_can documentation be an interface between different knowledges?_ +_trigger different kinds of economy around software?_ + +- interface between code, developer, world +- post meritocracy manifesto +- trans\*femminist server whishlist - 360 degrees of proximity diff --git a/chapters/03_world.md b/chapters/03_orienting_software.md similarity index 100% rename from chapters/03_world.md rename to chapters/03_orienting_software.md