ahh hello
parent
c7872ba6d7
commit
3884ce2694
Binary file not shown.
|
After Width: | Height: | Size: 115 KiB |
@ -0,0 +1,30 @@
|
|||||||
|
html,
|
||||||
|
body {
|
||||||
|
font-size: 21px;
|
||||||
|
line-height: 1.4;
|
||||||
|
}
|
||||||
|
|
||||||
|
h1 {
|
||||||
|
font-family: "Redaction 35";
|
||||||
|
line-height: 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
img {
|
||||||
|
border: 1px solid currentColor;
|
||||||
|
max-width: 100%;
|
||||||
|
object-fit: contain;
|
||||||
|
}
|
||||||
|
|
||||||
|
hr {
|
||||||
|
break-before: always;
|
||||||
|
}
|
||||||
|
|
||||||
|
li {
|
||||||
|
margin-bottom: 24px;
|
||||||
|
}
|
||||||
|
|
||||||
|
@media print {
|
||||||
|
.pagebreak {
|
||||||
|
page-break-before: always;
|
||||||
|
} /* page-break-after works, as well */
|
||||||
|
}
|
||||||
@ -0,0 +1,111 @@
|
|||||||
|
<!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>
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 714 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 248 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 420 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 333 KiB |
Loading…
Reference in New Issue