diff --git a/1dl/hello-word.1dl b/1dl/hello-word.1dl new file mode 100644 index 0000000..d13eb87 --- /dev/null +++ b/1dl/hello-word.1dl @@ -0,0 +1,27 @@ +(hello word) + +[description] +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. + diff --git a/1dl/opening.1dl b/1dl/opening.1dl new file mode 100644 index 0000000..ea0b663 --- /dev/null +++ b/1dl/opening.1dl @@ -0,0 +1,4 @@ +(Opening) +[description] +An opening is a declaration of intents, it manifests intentions. These intentions are glued together in the smallest context possible of a sentence. They are like a trailer for a movie, or the thumbnail of a youtube video. Often exagerate, click-bait, ideological. How and why these different facets come together? They are a visibile traces of choices made during development, choices that sometimes are made evident within the documentation, and sometimes remain unanswered. + diff --git a/flat.js b/flat.js new file mode 100644 index 0000000..dbf2b50 --- /dev/null +++ b/flat.js @@ -0,0 +1,71 @@ +import {open, mkdir, writeFile, readdir} from 'node:fs/promises' + +const inDir = './1dl/' +const outDir = './public/pathways/' +const files = await readdir(inDir) + + + + + +const syntax = () => { + const t = /^\(.*\)/ + const s = /^\[(.*?)\]/ + const n = /^(-->)/ + return {t, s, n} +} + + + +const parse = async (filepath) => { + const file = await open(filepath) + + const {t, s, n} = syntax() + + const parsed = [] + let currentTitle = "" + let currentSection = "" + + for await (let line of file.readLines()) { + line = line.trim() + + if (!line.length) continue + + if (line.match(t)) { + currentTitle = line.slice(1, -1) + parsed.push({title: currentTitle}) + continue + } + + if (line.match(s)) { + currentSection = line.slice(1, -1) + parsed[parsed.length-1][currentSection] = [] + continue + } + + if (line.match(n)) { + let note = line.slice(2) + parsed[parsed.length-1][currentSection].push({note: note}) + continue + } + + parsed[parsed.length-1][currentSection].push(line) + + } + + return parsed +} + +const pathways = [] + + +for (const file of files) { + const parsed = await parse(inDir+file) + + let filename = file.replace('.1dl', '') + pathways.push({slug: filename, ...parsed[0]}) + writeFile(outDir + file + '.json', JSON.stringify(parsed)) +} + +writeFile('./src/assets/pathways.json', JSON.stringify(pathways)) + diff --git a/index.html b/index.html index 795e4fb..aed285b 100644 --- a/index.html +++ b/index.html @@ -2,7 +2,7 @@
- +
- Edit
- components/HelloWorld.vue
to test HMR
-
- Check out - create-vue, the official Vue + Vite starter -
-- Install - Volar - in your IDE for a better DX -
-Click on the Vite and Vue logos to learn more
- - - diff --git a/src/components/Pathways.vue b/src/components/Pathways.vue new file mode 100644 index 0000000..c4bd3a3 --- /dev/null +++ b/src/components/Pathways.vue @@ -0,0 +1,21 @@ + + ++ +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? +
+ ++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. + +
+ ++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. +
+ + ++ 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. +
+ ++ {{section}} +
+ ++ {{section}} +
+ +