Hello Worlding - Pathways through code documentation

Hello Worlding is a network of pathways to walk through different ways to read, write and think with code documentation.

Each pathway is a reader made of READMEs: a collection of text files that usually accompany software to provide insights and explanations about what's going on in the code. Each pathway focuses on a particular approach or method to highlight the potential of code documentation to create worlds around the making of software.

Here some context

The nature of code documentation is to create entry points for people to participate in programming practices. To encode and filter knowledge, and ultimately to share it with others. This "nature", however, does not come without issues. It makes a lot of assumptions about who's reading, expecting experts, or engineers, or dudes. Its language is unwelcoming: too dense, too technical, very gendered and unable to address anyone but the neurotypical-white-cis-male programmer. Documentation requires an enormous amount of care, energy and time to be maintained, and it's done always out of budget, always as a side project, always at the end, and only if there's time left.

Even by doing a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface whose reach extends through time and space. Time because it meets programmers at different moments in their lives: from the hello world till the how to uninstall, and it influences thinking about software continuously. Space because it comes in many different possible formats, and can shapeshift to serve different occasions: from simple .txt files to entire websites, from coding workshops to comments in the source code to series of video tutorial.

The question then becomes: can we make use of these backdoors to infiltrate programming practices and open more entry points from within?

A README is an interface between the code, the user, the developer, and the world. Living close to the source code, but at the same time being less rigid and more expressive, it seems to be an ideal surface to influence software development practices. 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. A way to produce narrations around software. To create a world for the code to inhabit, to 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.

Here some background

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

Here some technical details

Hei, I'm not really sure about this setup, but think it's worth trying. The plan is to stay simple but expressive, and have fun during development.

Structure of the frontend:

• Homepage
  • intro text
  • list of pathways
  • list of all readmes
    • readme is a link + descriptions of why is special
• Pathway page
  • intro
  • list of pathway's readmes
    • again readme is a title, link and description of why is special
• About page
  • Longer description, the one used in the readme here could be a good starting point. Need to stress a bit more the idea of pathway.
  • Info on how to collaborate, link to repo, license, clerical stuff
• Activation page ????????????
  • text on this idea of snapshot in relation to pathways
  • documentation of snapshot
  • can host documentation and info about workshops etc.

Think about it as a writing machine! To say: ok now i'm working on this pathway that is focused on the usage of a certain word, It can be a process to annotate how this usage change over time for example.

Note that: a readme can appear in different pathways for different reasons! And that's why we are talking about network of pathways.

Plan and recipe

There is a folder with a .1dl file per pathway. This format allow for a structured yet expressive way of writing and annotating the list of readmes. Plus is something that build on a previous idea so guess it makes sense to trust of ancient intuitions.

Every pathway file has a structure similar to the example presented here.

The first (title) is the name of the pathway, along with a description for context. The other (title)s point each at readme file or a section of it, with again a small description of why they are special or related to the pathway.

(hello wording)

[context]
There are words around code: they create entry points and help understand software. They offer ways to reason about programming, they highlight certain features and hide undesired flaws. They describe the surroundings of an application: how does it interact with neighbouring systems and how does it address involved developers. These words make worlds around code. Worlds with embedded values, active actors and politics of participation. This pathway focuses on the usage of words and technical terminology in README files, on the assumption they imply, on the ways they are choosen. These README play by avoiding or insisting on specific terms, inflating tech jargon and opening backdoors for the participation of different sensibilities in the making of code. 


(flask-example)

[where]
https://git.xpub.nl/manetta/flask-example/src/branch/documentation

[what]
a piece of documentation written together with @chae.
there is a particular attention to write in a welcoming way, in a way to encourage green developers to familiarize with the development workflow. To address this particular public every technical detail (.env files, .gitignore, the usage of terminal), is inflated and explained pointing at useful resources.  


(pad-bis)

[where]
https://git.xpub.nl/kamo/pad-bis#deployment-production

[section]
Deployment and production

[what]
Trying to reclaim the usage of terms such as "deployment" and "production", in order to problematize their normalized context and offer a redemption-arc by using them in a different way. Rewrite this note because it's overengineered. 

These files are stored in the same repo as the whole app. A programmer voice inside me is protesting and at some point would like to move the .1dl archive in a dedicated place, to separate contents from code. I get it, but I also learned to cultivate this subtle sense of programming discomfort to see what's behind.

The idea is to parse the files and transform them to something like json on git PUSH webhook. I wrote a simple parser in Python some months ago, see flat.py.

These json pathways could then be used to render the website, and serve it as static pages. In this way SEO and requests would not be a problem, and helloworld.com could be served directly by NGINX. I would like to use Vite for that, in order to have the comfort of using Vue and single file components.

There is still a bit of ??? concerning how to react to the webhook. And again, inside me live two wolves. One says:

Think that to begin with will go with a small flask server, but I would prefer something smaller and simpler, to not juggle between javascript and python too much.

While the other:

No no, it's ok. Biodiversity is more interesting, let leave things distributed around different languages and think about it later.