From bff0cf0d80bda2ed4e9964df24ad8879a348eaee Mon Sep 17 00:00:00 2001 From: "kam (from the studio)" Date: Thu, 19 Jan 2023 16:23:22 +0100 Subject: [PATCH] table of content --- readme.md | 71 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 52 insertions(+), 19 deletions(-) diff --git a/readme.md b/readme.md index 8e70b5a..854ada4 100644 --- a/readme.md +++ b/readme.md @@ -38,33 +38,66 @@ The critical and theoretical research will be weaved around the actual documenta 0. **Coding Contingencies** Situate software as cultural object and proposes documentation as a surface to explore it. - - Context around software, software studies + - Context around software + - refer to software studies + - Define software documentation - reference, how-to, guide, tutorial - - here we are not focusing on one specific format, bur rather to a form of care (for users, for software, for context) - - - Introduce issues around software and documentation [probably articulated better later on] - - Propose documentation as a way to address these issues [probably articulated better later on] + - here we are not focusing on one specific catch-all format + - rather to a form of care (for users, for software, for context) + - in the context of situated software - Question: mention the context of situated software here ?? + - Introduce issues around software and documentation [chapters overview] + - Propose documentation as a way to address these issues [articulated better at the end] 1. **Participation** - Who gets to write, and who is forced to do it? How does development and technical writing interact? Is the technical writer a subaltern position in the industry of software development? What about users? + How does development and technical writing interact? + Who gets to write, and who is forced to? + Is the technical writer a subaltern position in the industry of software development? + Involvement of end-users? + + - Historical overview of how software documentation format changed + + - (from printed technical manual to wiki and discord server) + - from highly centralized manuals to open and collaborative documents + + - Actors involved and hierarchies (from developers to end-users, gendered work, subaltern work) + + - Is writing documentation subaltern work? + - No one wants to write documentation, or pay someone to do it + - Historical accounts of who writes?? (Outside of time, Ullman) (Into the ground C++, Gabriel) + - The post-meritocracy manifesto (Ehmke, 2018) + "We acknowledge the value of all contributors as equal to the value of contributors who are engineers." + +2. **Destination** + How does it produce public? + Who is this documentation for? + How does it relate with a bigger context? + + Who can access it? + Where is the documentation hosted? + + - Assuming a certain kind of reader (often male, often white, often with formal education) + + - Read the feminist manual (Karayanni, 2021) + - Programming for the millions (Ullman, 2016) + + - situated software require situated documentation [case studies] + - Wheatering software winter, about the impossibility to print out documentation, tshirt docs (100R, 2022) + - Accessible documentation + - Welcoming documentations - - Historical overview of how software documentation changed (from printed technical manual to wiki and discord server) - - Printed manuals - - Manpages - - Websites - - Wikis - - Online communities - - Reflection on actors involved and hierarchy (from developers to end-users, gendered work, subaltern work, post-meritocratic manifesto) +3. **Tone and style** -2. **Destination** - Who can read documentation? Who can access? Where is the documentation hosted? How does it relate with a bigger context, if any? + How to make documentation more accessible? + How to create multiple entry points in a complex topic? + How to address different kind of users, and not just a generic one? + How to orientate software in the world? -3. **Tone and style** - How to make a documentation more accessible? How to create multiple entry points in a complex topic? How to address different kind of users, and not just a generic one? How to orientate software in the world? + - Documentation as an interface between different knowledges 4. **Susteinability** - How to face the lack of resources when approaching technical writing? Strategies to share workloads and collaboration. Strategies to take care of shared piece of software. + How to face the lack of resources when approaching technical writing? + Strategies to share workloads and collaboration + Strategies to take care of shared piece of software.