From 0a08074ead4841631cbdf23247e35d04683b8aa1 Mon Sep 17 00:00:00 2001 From: "kam (from the studio)" Date: Thu, 16 Mar 2023 18:36:45 +0100 Subject: [PATCH] notes with cristina --- chapters/01_who_is_reading.md | 29 +++++++++++++++++++++++++++++ notes.md | 3 +++ queue.md | 7 +++++++ 3 files changed, 39 insertions(+) diff --git a/chapters/01_who_is_reading.md b/chapters/01_who_is_reading.md index f495382..8c17b3b 100644 --- a/chapters/01_who_is_reading.md +++ b/chapters/01_who_is_reading.md @@ -116,6 +116,35 @@ Message in console printed by Bridle to welcome users - source: booktwo.org - often documentation doesn't offer entry points for beginners, or a sense of direction, this esp a problem with hypertexts ``` +- who writes code documentation tends to assume a certain kind of reader, to talk a specific language, to refer to a particular context + +sections + +__expert reader, formerly educated reader__ + +takes for granted the technical level of the reader, +takes for granted a specific lexicon, +relates with external sources without referring to them + + +__male! developer often addressed as he/him__ + + +- within a particular cultural niche! western +- dude + + + + + + + + + + + + + Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers. Who is going to read this piece of documentation? diff --git a/notes.md b/notes.md index f0b5626..9e2a423 100644 --- a/notes.md +++ b/notes.md @@ -1,5 +1,8 @@ # Notes to the self +## Tutorial with Cristina + +- documentation as gardening, need for constant maintainance ## Aaaaaaaaaaaaaaaaaaaaaaaaaa diff --git a/queue.md b/queue.md index f952d94..c7d01f5 100644 --- a/queue.md +++ b/queue.md @@ -17,3 +17,10 @@ - [solarpunk - zines](https://solarpunk.cool/zines/) - [Bridle - welcome.js blog post](https://web.archive.org/web/20200219181416/http://booktwo.org/notebook/welcome-js/) + +- [who called it “writing documentation” and not “manual labor”](https://mastodon.social/@NeoNacho/109980998747734857) +- [documentation as harvesting](https://documenta-fifteen.de/en/news/harvesters-and-harvesting-practice-at-documenta-fifteen/) +- [Lumbung space](https://panduan.lumbung.space/s/272026ff-57fd-4894-8d68-58606c77044c/doc/who-can-use-lumbungdotspace-5mJrAaF3dy) +- [Lumbung tools](https://panduan.lumbung.space/s/9f7eb837-c8b8-4b64-ad68-a298bde8ab36) +- [titipi methods](https://titipi.org/?methods) +- [bug report geohacker](https://volumetricregimes.xyz//index.php?title=We_Have_Always_Been_Geohackers)