From 460d9145e637fbaaf526bbeef7d5eca67cfb57c4 Mon Sep 17 00:00:00 2001 From: Francesco Luzzana Date: Tue, 7 Feb 2023 15:19:48 +0100 Subject: [PATCH] first chap --- .gitignore | 1 + bibliography.md | 5 +++ chapters/00_intro.md | 2 +- chapters/01_lowering_barriers.md | 60 +++++++++++++++++++++----------- 4 files changed, 47 insertions(+), 21 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..600d2d3 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.vscode \ No newline at end of file diff --git a/bibliography.md b/bibliography.md index da5c40c..70d5787 100644 --- a/bibliography.md +++ b/bibliography.md @@ -14,3 +14,8 @@ add: how to cite?? - A Wishlist for Trans\*femminist Servers. 2022. https://etherpad.mur.at/p/tfs + +https://ironicsans.substack.com/p/the-strangest-computer-manual-ever +https://www.ironicsans.com/2010/02/they_dont_make_computer_manual.html#comment-403451 +https://www.ironicsans.com/ace100.pdf +https://www.ironicsans.com/ace1000.pdf diff --git a/chapters/00_intro.md b/chapters/00_intro.md index 9c39685..c8df7a2 100644 --- a/chapters/00_intro.md +++ b/chapters/00_intro.md @@ -26,7 +26,7 @@ The main focus of this research is to explore software documentation as surface 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. It reaches not only beginners, but experienced programmers as well. It affects thinking about software continously. +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 continously, and from different perspectives. 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. diff --git a/chapters/01_lowering_barriers.md b/chapters/01_lowering_barriers.md index 0c88a18..080e4f8 100644 --- a/chapters/01_lowering_barriers.md +++ b/chapters/01_lowering_barriers.md @@ -1,37 +1,60 @@ +# Who is reading + _could documentation be a surface to build worlds around software?_ -> aknowledge doc importance +``` +build worlds? + where software circulate + who gets to use it + political of the software -- software without documentation is invisible -- documenting code from different distances -> what it should do +yes because + it's often first thing one reads when approaching software # getting started + it's consulted not just from beginner, but also experienced users #a code companion + different docs for different readers -> what it often does intead +yes but + it should stop assuming its reader + it should be more welcoming for different kind of knowledges +``` -how doc +## Getting started -- different documentations for different readers +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. + +At the very first encounter with a new script, details about its source code are unknown. Programming is a play _in medias res_, and documentation acts the role of narrator. Describing how functions are stitched together, or an algorithm is implemented, it sets the stage for developers to participate. Showing the different steps of a program and how they are connected, it offers entry points for interventions. + +For example Vue.js, the popular library for building web user interfaces, explains with a diagram the lifecycle of its components: at which moment data are received from a server, at what point an element is rendered on screen, and when it will disappear. What at the beginning feels like magic, gradually appears more clear. Presenting a structure means also presenting a way to reason about it. The reader gains some understanding and agency over the tools they are about to use. + +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 & Soon, 2022) + +``` +better transition above +better conclusion below +``` + +The initial imprinting of documentation is a vantage point to orientate code in the world. + +## A code companion -probs +The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the specifics of a particular programming language or platform. Sometimes for the web, sometimes for a hardware component, sometimes for a different operative system. These _specs_ make every piece of code a bit alien and peculiar. Tinkering with code is not just knowing by heart a programming language, but rather having to deal with a lot of different recipes for different occasions. -- who is reading? -- not for beginner +Documentation is not just for beginners: it's a code companion. It relates with code continuously. Even experienced programmers must refer to the docs when first encountering a software, and return to the references when they need a refresher on the particular syntax of a specific command. One never stops reading. Documentation acts as a portal to different moments in the life of a programmer: from the _hello world_ to the _how to uninstall_. + +- documenting code from different distances +- different documentations for different readers -props +--- -- lowering barriers and creting entry points -- readme exampless +- lowering barriers and creating entry points +- readme examples - p5js debug examples ## Software without documentation Software without documentation is invisible. Therefore it is important to document it. Software without documentation tends to slip away, to disappear. Therefore it is important to have some notes on how does it work, how does it tackle the problem to solve. -The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the small specifics of a particular programming language or platform. These specifics make every piece of code alien and peculiar. Tinkering with code is not just knowing by hearth a programming language, but rather having to deal with a lot of different recipes. - -Opening 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. - These guidelines are helpful when sharing programs with others, as well with future selves. They provide an entry into the messy relationship between developers and machine. --- @@ -50,9 +73,6 @@ Documentation can happen at different distances from code: directly in source wi Who is writing could be the very same developer or someone else. Writings come with different approaches and intentions, and as response to different needs. -Documentation is not just for beginners: it's a code companion. It affects code continously. -Even experienced programmers must refer to the docs when first encountering a software. - ## Different documentation for different readers Documentation comes in many different forms. Daniele Procida offers a systematic approach to organize this wealth of formats (diataxis.fr, 2017).