You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
112 lines
4.8 KiB
HTML
112 lines
4.8 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8" />
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<title>Software documentation as a form of care???</title>
|
|
<link rel="stylesheet" href="style.css" />
|
|
</head>
|
|
<body>
|
|
<h1>The problem with <br />software documentation</h1>
|
|
<img src="trolley.jpg" alt="" srcset="" />
|
|
<p>
|
|
Software comes from a really specific occidental cultural tradition. Software tends to
|
|
priviledge masculine, binary, exploitative and extractive practices. Software is
|
|
shrouded in technical obscurity. Software comes invisible, transparent, neutral.
|
|
Software models the world in order to control it.
|
|
</p>
|
|
<p>
|
|
To make software means not only to write code, but also to take a stance regarding this
|
|
trends. To make software means not only to write code, but also to create a context and
|
|
community around it.
|
|
</p>
|
|
<p>
|
|
Documentation is a space that interfaces the different actors around software. Software
|
|
documentation is a space with potential to renegotiate and reclaim given margins and
|
|
entry points. It is a chance to overwrite what is normalized, and let different
|
|
knowledges and voices participate in the discourse around software.
|
|
</p>
|
|
|
|
<p>
|
|
Documenting software is a complex practice. Documenting software is a process of
|
|
translation. Writing documentation it's more difficult than writing software itself. It
|
|
requires a lot of time and energy, and it involves many different skills: writing,
|
|
coding, knowing how to share and at which intensity. It's a collaborative practice that
|
|
could open to different voices.
|
|
</p>
|
|
<p>As a piece of code would write: I am documented, therefore I am.</p>
|
|
|
|
<p>
|
|
Coding is not just production of software, but also production of knowledge. A dialogue
|
|
between human and more-than-human actors. The guestlist of this conference of the bits
|
|
is often compiled by chance: the choice of a particular programming language, the coding
|
|
style, the development environment and ecosystem, the infrastructure that runs the code,
|
|
and so on, are the result of specific contingencies.
|
|
</p>
|
|
|
|
<p>
|
|
These contingencies are situated in precise contexts, and these contexts are different
|
|
one from another. Programming is not just sharing code, but sharing context. Programming
|
|
means to provide a point of view and a perspective to look at the world, before
|
|
attempting to get some grip onto it with a script. That's the reason why even if source
|
|
code, even when obfuscated, speaks for itself, it cannot always cast light around its
|
|
surroundings.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
Documentation is a way to produce narrations around software. To create a world for a
|
|
software 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 of software. It's a surface
|
|
that could host ideas in close contact with codes, letting them entangle and shape each
|
|
other.
|
|
</p>
|
|
<div class="pagebreak"></div>
|
|
<h1>The plan</h1>
|
|
|
|
<ul>
|
|
<li>
|
|
Focus on software documentation as an interface between code, users, developers,
|
|
communities, and the world.
|
|
</li>
|
|
<li>
|
|
Research how writing software documentation changes depending on the context and
|
|
actors involved.
|
|
</li>
|
|
<li>
|
|
Experiment with software documentation as a generative device to keep thinking
|
|
through code from different perspectives.
|
|
</li>
|
|
<li>
|
|
Explore software documentation as iterative process, as a format that grows and
|
|
shrinks through versioning and embrances branching to adapt to specific
|
|
environments.
|
|
</li>
|
|
<li>
|
|
Develop tools to facilitate rich software documentation. To assist and stimulate the
|
|
writing process with prompts and gently reminders that software documentation is a
|
|
form of care.
|
|
</li>
|
|
<li>
|
|
Question the nature of the documentation: what does it take for granted? For what
|
|
kind of public it is produced, and what kind of public does it produce? How does it
|
|
normalize the context around the software? What are its politics of access? How does
|
|
it create entry points and how does it gatekeep?
|
|
</li>
|
|
|
|
<li>
|
|
Try to infiltrate the industry of software development through documentation.
|
|
Attempt to expose their public to these questions in subtle ways. Offer entry points
|
|
and escape routes from the universal solution proposed by big corporates.
|
|
</li>
|
|
</ul>
|
|
</body>
|
|
</html>
|