@ -26,7 +26,7 @@ The main focus of this research is to explore software documentation as surface
A way to situate programming in specific contexts.
Documentation brings an understanding on software by disclosing its magic. It reveals what can be done with it, and where are the limits. By lowering barriers and creating entry points, documentation broadens participation.
Documentation brings an understanding on software by disclosing its magic. It reveals what can be done with it, and where are the limits. By lowering barriers and creating entry points, documentation broadens participation. It reaches not only beginners, but experienced programmers as well. It affects thinking about software continously.
Documentation is a space that interfaces between the code, the user, the developer, and the world. A space where to welcome different voices: not just engineers, not just experts, not just dudes. A space to aknowledge the massive labor of care besides technicalities, often marginalized by coding culture.
_could documentation be a surface to build worlds around software?_
_Documentation as a way to lower barriers & create entry points_
contents:
why doc
> aknowledge doc importance
- software without documentation is invisible
- documenting code from different distances
- not just for beginner
> what it should do
> what it often does intead
how doc
- different documentations for different readers
- see diataxis
probs
@ -28,18 +26,19 @@ props
## Software without documentation
Software without documentation is invisible. Therefore it is important to document it.
Software without documentation tends to slip away, to disappear. Therefore it is important to have some notes on how does it work, how it tackles the problem to solve.
Software without documentation is invisible. Therefore it is important to document it. Software without documentation tends to slip away, to disappear. Therefore it is important to have some notes on how does it work, how does it tackle the problem to solve.
The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the small specifics of a particular programming language or platform. These specificities make every piece of code alien and peculiar.
The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the small specifics of a particular programming language or platform. These specifics make every piece of code alien and peculiar. Tinkering with code is not just knowing by hearth a programming language, but rather having to deal with a lot of different recipes.
Opening undocumented code feels like being a small ant walking on a big painting. You can see the strokes of a brush, and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides some guidance through the bunch of functions and statements that makes software.
Opening undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush, and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software.
These guidelines are helpful when sharing programs with others and future selves. They provide an entry into the messy relationship between developers and machine.
These guidelines are helpful when sharing programs with others, as well with future selves. They provide an entry into the messy relationship between developers and machine.
---
Being programming slightly different from cycling, people tend to forget what their code does, and how did it get there.
_bonus caption for images:_
Being programming slightly different from cycling, people tend to forget what their code does, and how did it get there. (Maybe because it doesn't involve muscle memory?)
Software documentation is a defensive mechanism operated from our past selves to protect the present and future ones.
@ -47,19 +46,12 @@ Cuneiform writing and comments. (even though this is cuneiform writing and synta
## Different distances
Documentation happens at different distances from code: it can be inserted directly in source with lines of comment that are ignored by the machine, but much appreciated by fellows developers, or it can be printed in books, along with pages and pages of examples and references.
Who is writing could be the very same developer or someone totally different.
Every distance comes with different approaches and intentions, and responds to different needs.
Documentation is a way to make the intentions behind code public.
Documentation can happen at different distances from code: directly in source with lines of comment—ignored by the machine, but much appreciated by fellows developers—or it can be printed in books, along with pages of examples and references.
## Not just for beginners
Who is writing could be the very same developer or someone else. Writings come with different approaches and intentions, and as response to different needs.
Documentation is not just for beginners: it's the code companion.
It does not expire first steps.
It affects code continously.
Documentation is not just for beginners: it's a code companion. It affects code continously.
Even experienced programmers must refer to the docs when first encountering a software.
