## What do you want to make?
Compile a list of resources to explore the _documentation of coding related practices_ from a community-based perspective, that is the process of sharing knowledge and making worlds together around _situated software_ (Shirky, 2004).
These resources will be of various nature: tools, thoughts, anecdotes, excercises, prompts, strategies, ... They will offer entry points to articulate _software documentation_ as a form of care.
Compile a list of resources to explore the _documentation of coding related practices_ from a community-based perspective, as a process of sharing knowledge and making worlds together around _situated software_.
To work within the constraints of a structure such as the list will help to think through the complexity of dealing with a double unknown: the one of software and the one of situatedness. This complexity will hopefully be preserved and encoded in the relations between different items.
(Imagine a [GitHub list](https://github.com/everestpipkin/tools-list) gradually branching like a coral reef, with the items _interfering_ with each other, in something that resembles more that classic list from Borges than a dry index of references.)
Some elements of the list will relate to the materiality and surfaces where documentation is hosted, while others will engage more with the actors and frameworks entangled in the process.
These resources will be of various nature: tools, thoughts, anecdotes, excercises, prompts, strategies, ... They will offer entry points to articulate _software documentation_ as a form of care.
--Following to the idea that items in a list aren't necessarily responses to the same questions, yet they hang togheter (Law, Mol 2002)
Imagine a [tools list](https://github.com/everestpipkin/tools-list) (Pipkin, 2022) gradually branching as a coral reef, with the items _interfering with each other_ (Haraway, 1988), resembling the heterogeneous Celestial Emporium reported by Borges (Borges, 1968). Some elements of the list will relate to the materiality and surfaces where documentation is hosted, while others will engage more with the actors and frameworks entangled in the process.
_Software documentation_ is not just a list of technical procedures, but also a matter of providing context and orientate code in the world. In the same way, the list is meant to be a texture where to weave together multiple voices and diverse registry, in order to re-enchant the making of software.
_Software documentation_ is not just a technical list of procedures, but also a matter of providing context and orientate code in the world. In the same way, the list is meant to be a texture where to weave together multiple voices and diverse registry, in order to re-enchant the making of software.
> "A list doesn't have to impose a single mode of ordering on what is included in it. Items in the list aren't necessarily responses to the same questions but may hang together in other ways... a list differs from a classification in that it recognizes its incopleteness. It doesn't even need to seek completeness. If someone comes along with something to add to the list, something that emerges as important, this may indeed be added to it." \_[John Law and Annemarie Mol, Complexities: Social Studies of Knowledge Practices]
## Why do you want to make it?
This project grows out of the frustration of finding myself often trying to deal with bad documented pieces of software. While for sure there is some thrill in understanding how to stitch together those codes, the lack of documentation poses a great hindrance for the participation of diverse knowledges in the making of software.
This project grows out of the contradiction of being frustrated in having to deal with undocumented pieces of software, and at the same time never documenting anything. While for sure there is some thrill in understanding how to stitch codes together, the lack of documentation poses a great hindrance for the participation of diverse knowledges in the making of software.
At the same time, this very lack of documentation could be used as a starting point.
<!-- more about concrete approach? could it be permacomputing? -->
<!-- rephrased as software as care? -->
<!-- care for who? other participant, dependencies, environment? -->
Documentation is a space that interfaces between the code, the user, the developer, and the world. A space with potential to renegotiate and reclaim given margins and entry points. A chance to overwrite what is normalized, and let more voices participate in the discourse that is software.
<!-- more on who i would like to participate more -->
Documentation is a way to produce narrations around software. To create a world for the code to inhabit, to give it affordances and stretch what is possible to do or to think with it. Documentation is a space for the political in the software. A surface that could host ideas in close contact with code, letting them entangle and shape each other.
## How do you plan to make it?
- Read software documentation
- (manuals, guides, references, tutorial)
- (good ones, bad ones, ...)
- Which software needs documentation?
- Wich documentation could use some rework?
- Which software do we want to document?
<!-- ↑ should this be formulated more as a plan and less as a question? -->
- Study documentation frameworks
- Prototype small systems to gather items for the list
- Write software documentation
- Experiment with contents, tone and style
- Get in touch with communities related to situated software
- Meet the actors involved
- Focus on the writing process
- Tap into surrounding contexts
- Meet the actors involved
- Gather impressions and insights
- Host them in a list
- Leave it open for others to contribute
@ -77,45 +65,56 @@ Documentation is a way to produce narrations around software. To create a world
- Think about a glossary and possible formats to test some concept in a small scale
- Experiment writing documentation for XPUB prototypes
- November
- Experiment writing documentation for projects outside XPUB
- Artistic and commercial ones.
- Which software do we want to document?
- Tap into networks related to situated software
- Participate to events! Software is a public discourse don't be too shy
- December
- Archeology of software documentation.
- Field research of the current trends in software documentation.
- Explore different contexts and different coding languages.
- January
- Follow up on the outcomes of the different hackpacts. Focus on
1. materiality (style, contents, forms),
1. materiality (style, contents, forms)
2. context (actors, timeframe, hosting)
- February
- Research possible formats for the list outcome.
- February
- What surface could host this different factes together?
- Fast daily prototypes
- Fast daily prototypes or field research
- March
- Follow up on February daily prototypes
- Plan for production
- April
- Production!
- First in the form of fast and iterative prototyping, then fine tuning and polishing.
- Production in the form of fast and iterative prototyping
- Fine tuning and polishing.
- Think about graduation exhibition and collective pubblication.
## Who can help you and how?
- people interested in the making of software
- people interested in the narrative around software
- critical code studies working group
- 100 rabbits
- permacomputing
- Peers involved in situated software contexts (that is also the public of this project)
- People interested in the making of software, either specialized or not
- People interested in the narrative around software
## Relation to previous practice
I'm interested in the development of site-specific software. My artistic and design practice has always relied on the development of custom software to facilitate agency-on and comprehension-of complex systems. The tools themselves were never the main focus though, but rather just instruments to activate and be activated within particular contexts. Tools tailored to specific moments and then forgotten.
I'm interested in the development of site-specific software. My artistic and design practice has always relied on the development of custom software to facilitate agency-on and comprehension-of complex systems. The tools themselves were never the main focus though, but rather just instruments to activate and be activated within particular contexts. Tools tailored to specific moments and then forgotten. Situated Software (www.gwern.net, 2004).
During the first year at XPUB the approach started to change. Working together with my classmates let me realize the importance of sharing tools. To develop not just for yourself, but also for others. Code as a common. How important it is to create a space for these tools to circulate, and how important are the narrations we build around these instruments. In this sense software development could be seen as a form of care, as well as a form of publishing.
Since last year I'm prototyping writing machines in order to keep track of what happens around XPUB. Some examples are [this very section of the Soupboat](/soupboat/~kamo/) that is a way to document projects, the [Padliography](/soupboat/padliography/) that is a way to archive documents and links, the [xquisite branch](/soupboat/xquisite/draw/BUCockhPVwHxGARDhSMKgn) made during SI17 that is a branching take on the exquisite corpse game, etc. Probably to develop software is my strategy to get grip on the world. Every writing machine implies a different way to think about your contents. The plan is to develop something as well for this research process.
After the work in the past Special Issues, I'm trying to shift from compulsive development to susteinable development. Sustainable in relation to the context and the other actors involved in the process. This requires to learn how to balance between different priorities, to understand when to develop something from scratch and when to participate into already existing discourses. It means to learn how to balance between accessibility, susteinability and flexibility.
@ -136,40 +135,19 @@ These contingencies are situated in precise contexts, and these contexts are dif
To make place for code turns to be a necessary act of care in the process of sharing knowledge. This does not mean to constrain the usage of some piece of software, or provide opinionated solutions or tutorials, but rather letting others know where does this code come from, and where it would like to go.
## References/bibliography
- Fuller, M. ed. 2008. Software Studies: A Lexicon. Cambridge, Massachusetts: The MIT Press.
- Ullman, E. (2013) Close to the machine: Technophilia and its Discontents. London, England: Pushkin Press
- Law, J ed. and Mol, A ed. (2002) Complexities: Social Studies of Knowledge Practices, Duke University Press Books
<!--- Bridle, J (2022) Ways of Being: Beyond Human Intelligence, Farrar, Straus and Giroux
- Bridle, J (2018) New Dark Age: Technology and the End of the Future, Verso -->
And then a list of possible references
<!--- Hayles, N K (2005) My Mother Was a Computer: Digital Subjects and Literary Texts, University of Chicago Press -->
<!--- Sterling, B (2005) Shaping Things, MIT Press -->
<!--- Mackenzie, A (2006) Cutting Code; Software and Sociality, International Academic Publisher -->
<!--- Suchman, L A (1987) Plans and Situated Actions: The Problem of Human-Machine Communication, Cambridge University Press -->
<!-- Balibar, É (2020) On Universals: Constructing and Deconstructing Community, Fordham University Press -->
<!--- Cantwell Smith, B (1996) On the Origin of Objects, Bradfor Book -->
<!--- Knuth, D E (1973) The Art of Computer Programming, Addison-Wesley -->
<!--- Knuth, D E (1992) Literate Programming, Center for the Study of Language and Information -->
- Brodie, L (1984) Thinking Forth, Punchy Publising
<!--- Wendy Hui Kyong Chun, "On Software, or the Persistence of Visual Knowledge" (2005) Grey Room. 18 -->
## References
<!--- Lethbridge, Chantelle & Sim, Susan & Singer, Janice. (1999). Software Anthropology: Performing Field Studies in Software Companies. -->
<!--- Crowston, Kevin and Howison, James, "The Social Structure of Open Source Software Development Teams" (2003). School of Information Studies - Faculty Scholarship. 123. -->
- Fuller, M. ed. (2008). Software Studies: A Lexicon. Massachusetts: The MIT Press.
- Haraway, D. (1988). Situated Knowledges: the Science Question in Feminism and the Privilege of Partial Perspective. Feminist Studies, 14(3), pp.575–599. doi:10.2307/3178066.
- Jorge Luis Borges (1968). Other inquisitions. New York Simon And Schuster Imp.
- Karayanni M. (2021). Read The Feminist Manifesto. [online] Available at: https://psaroskalazines.gr/pdf/rtfm_zine_screen.pdf.
- Law, J. and Mol, A. (2002). Complexities social studies of knowledge practices. Durham: Duke University Press.
- Li, J. (2020). Where Did Software Go Wrong? | Jesse Li. [online] Available at: https://blog.jse.li/posts/software/ [Accessed 10 Nov. 2022].
- Pipkin, E. (2022). Open source, experimental, and tiny tools roundup. [online] GitHub. Available at: https://github.com/everestpipkin/tools-list [Accessed 18 Nov. 2022].
- Procida, D. (2017). Diátaxis Documentation Framework. [online] diataxis.fr. Available at: diataxis.fr [Accessed 18 Nov. 2022].
- Shirky, C. (2004). Shirky: Situated Software. [online] Available at: https://www.gwern.net/docs/technology/2004-03-30-shirky-situatedsoftware.html [Accessed 11 Oct. 2022].
- Ullman, E. (2013). Close to the machine: Technophilia and its Discontents. London: Pushkin Press
- Shirky, C (2004) [Situated Software](https://www.gwern.net/docs/technology/2004-03-30-shirky-situatedsoftware.html)
@ -159,8 +159,6 @@ More specifically, I would like to focus on software documentation as a surface
> To make sense of multiplicity, we need to think and write in topological ways, discovering methods for laying out a space, for laying out spaces, and for defining paths to walk through these. _[John Law and Annemarie Mol, Complexities: Social Studies of Knowledge Practices]_
Since last year I'm prototyping writing machines in order to keep track of what happens around XPUB. Some examples are [this very section of the Soupboat](/soupboat/~kamo/) that is a way to document projects, the [Padliography](/soupboat/padliography/) that is a way to archive documents and links, the [xquisite branch](/soupboat/xquisite/draw/BUCockhPVwHxGARDhSMKgn) made during SI17 that is a branching take on the exquisite corpse game, etc. Probably to develop software is my strategy to get grip on the world. Every writing machine implies a different way to think about your contents. The plan is to develop something as well for this research process.
The topological way to think and write the thesis is to be found somewhere around:
