TODO: a file where to keep references

Worlding and Software

How do you chose a particular programming language, a coding style, a development environment and ecosystem, an infrastructure where to run the code, and so on?

These are not just technical choices, but rather coding contingencies.

These contingencies are situated in precise economical, cultural, creative, political, and technical contexts. Programming then is not just sharing code, but sharing context. It's providing a perspective to look at the world before attempting to get some grip onto it with a script.

How to offer a point of view through the lens of software?
Who get to participate in this process of making meaning?
How to create a discourse for the code to inhabit?
How to stretch the affordances of code, besides technicality, marketing, and advertisement?

Enter documentation

Could software documentation:

0. be a mean to explore these contingencies?
1. be an ideal surface to build worlds?
2. be an interface between different knowledges?
3. be a device to trigger different kinds of economy around situated software?

How can situated practices inform the process of documenting software? And how can situated software inform the process of technical writing?

Table of Contents (draft)

The thesis is composed of different texts: some provide context and critical background to situate the research, while others consist in experiments of actual documentation written for software developed within our course. Every piece of documentation will try to reflect on different angles.

The critical and theoretical research will be weaved around the actual documentations, in order to create a discourse and annotate the development of this practice.

0. Coding Contingencies
   Situate software as cultural object and proposes documentation as a surface to explore it.

   • Context around software

   • refer to software studies

   • Define software documentation

     • reference, how-to, guide, tutorial
     • 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

   • Introduce issues around software and documentation [chapters overview]

   • Propose documentation as a way to address these issues [articulated better at the end]

   1. Participation
      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."

1. 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

2. Tone and style

   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?

   • Documentation as an interface between different knowledges

3. 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.

TOC bis + math

1. Coding Contingencies (2000)
   Situate software as cultural object and propose documentation as a surface to explore it.

   1. Context around software, besides technicality (500)

   2. Introduce issues around software (1000)

      1. Biased and hostile environments
         • Toxic masculinity, encoded chauvinism, western monoculture
      2. Evergrowing complexity
         • Intimidating learning curve, disproportion of means, mistification
      3. The universal solution™
         • Techno solutionism, gray tech, ideology

   3. Propose documentation as a way to address these issues (500)

      1. Welcoming diverse knowledges
      2. Lowering barriers and create entry points
      3. Orientate software in the world

2. Documentation as an interface (3000)
   Aknowledge documentation as crossroad for different actors, as intersection between code, machines, developers, users. Articulate it as a vantage point from where to reason about software.

   0. Define software documentation

      1. Small historical overview: from printed manuals to discord servers
      2. Dyataxis framework: Reference, How-to, Guide, Tutorial

   1. Welcoming diverse knowledges

      • Who is writing?

      • Who will read?

      • Programming for the millions (Ullman, 2016)

      • Read the feminist manual (Karayanni, 2021)

      • Who is making of software?

      • A crowd besides developers

      • Post-meritocracy manifesto (Ehmke, 2018)

   2. Lowering barriers and create entry points

      • Paths through complexity

      • Demistifying

      • Bridle Welcome to console

      • Debugging (P5js Education Working Group, 2015)

   3. Orientate software in the world

3. Situated software requires Situated documentation (3000)