first setup
parent
f8661bd19f
commit
6d5cdada43
@ -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.
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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))
|
||||
|
||||
@ -0,0 +1 @@
|
||||
[{"title":"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."]},{"title":"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."]},{"title":"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."]}]
|
||||
@ -0,0 +1 @@
|
||||
[{"title":"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."]},{"title":"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."]},{"title":"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."]}]
|
||||
@ -0,0 +1 @@
|
||||
[{"title":"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."]}]
|
||||
@ -0,0 +1 @@
|
||||
[{"title":"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."]}]
|
||||
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>
|
||||
|
Before Width: | Height: | Size: 1.5 KiB |
@ -1,30 +1,16 @@
|
||||
<script setup>
|
||||
import HelloWorld from './components/HelloWorld.vue'
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<a href="https://vitejs.dev" target="_blank">
|
||||
<img src="/vite.svg" class="logo" alt="Vite logo" />
|
||||
</a>
|
||||
<a href="https://vuejs.org/" target="_blank">
|
||||
<img src="./assets/vue.svg" class="logo vue" alt="Vue logo" />
|
||||
</a>
|
||||
</div>
|
||||
<HelloWorld msg="Vite + Vue" />
|
||||
<h1>Hello Worlding</h1>
|
||||
|
||||
<div>
|
||||
pathways through code documentation practices
|
||||
</div>
|
||||
|
||||
<router-view></router-view>
|
||||
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.logo {
|
||||
height: 6em;
|
||||
padding: 1.5em;
|
||||
will-change: filter;
|
||||
transition: filter 300ms;
|
||||
}
|
||||
.logo:hover {
|
||||
filter: drop-shadow(0 0 2em #646cffaa);
|
||||
}
|
||||
.logo.vue:hover {
|
||||
filter: drop-shadow(0 0 2em #42b883aa);
|
||||
}
|
||||
</style>
|
||||
|
||||
@ -0,0 +1 @@
|
||||
[{"slug":"hello-word","title":"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."]},{"slug":"opening","title":"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."]}]
|
||||
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="37.07" height="36" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 198"><path fill="#41B883" d="M204.8 0H256L128 220.8L0 0h97.92L128 51.2L157.44 0h47.36Z"></path><path fill="#41B883" d="m0 0l128 220.8L256 0h-51.2L128 132.48L50.56 0H0Z"></path><path fill="#35495E" d="M50.56 0L128 133.12L204.8 0h-47.36L128 51.2L97.92 0H50.56Z"></path></svg>
|
||||
|
Before Width: | Height: | Size: 496 B |
@ -1,40 +0,0 @@
|
||||
<script setup>
|
||||
import { ref } from 'vue'
|
||||
|
||||
defineProps({
|
||||
msg: String,
|
||||
})
|
||||
|
||||
const count = ref(0)
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>{{ msg }}</h1>
|
||||
|
||||
<div class="card">
|
||||
<button type="button" @click="count++">count is {{ count }}</button>
|
||||
<p>
|
||||
Edit
|
||||
<code>components/HelloWorld.vue</code> to test HMR
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
Check out
|
||||
<a href="https://vuejs.org/guide/quick-start.html#local" target="_blank"
|
||||
>create-vue</a
|
||||
>, the official Vue + Vite starter
|
||||
</p>
|
||||
<p>
|
||||
Install
|
||||
<a href="https://github.com/vuejs/language-tools" target="_blank">Volar</a>
|
||||
in your IDE for a better DX
|
||||
</p>
|
||||
<p class="read-the-docs">Click on the Vite and Vue logos to learn more</p>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.read-the-docs {
|
||||
color: #888;
|
||||
}
|
||||
</style>
|
||||
@ -0,0 +1,21 @@
|
||||
<template>
|
||||
|
||||
<dl>
|
||||
<div v-for="pathway in pathways" :key="pathway.slug">
|
||||
<dt>
|
||||
<router-link :to="`pathways/${pathway.slug}`">
|
||||
{{pathway.title}}
|
||||
</router-link>
|
||||
</dt>
|
||||
<dd>{{pathway.description}}</dd>
|
||||
</div>
|
||||
</dl>
|
||||
|
||||
|
||||
</template>
|
||||
<script setup>
|
||||
|
||||
const props = defineProps(['pathways'])
|
||||
|
||||
</script>
|
||||
<style></style>
|
||||
@ -1,5 +1,10 @@
|
||||
import { createApp } from 'vue'
|
||||
import './style.css'
|
||||
import App from './App.vue'
|
||||
import router from '@/router'
|
||||
|
||||
createApp(App).mount('#app')
|
||||
|
||||
|
||||
|
||||
|
||||
createApp(App).use(router).mount('#app')
|
||||
|
||||
@ -0,0 +1,17 @@
|
||||
import {createRouter, createWebHistory} from 'vue-router'
|
||||
import Home from '@/views/Home.vue'
|
||||
import About from '@/views/About.vue'
|
||||
import Pathway from '@/views/Pathway.vue'
|
||||
|
||||
const routes = [
|
||||
{path: '/', name: 'Home', component: Home},
|
||||
{path: '/about', name: 'About', component: About},
|
||||
{path: '/pathways/:slug', name: 'Pathway', component: Pathway}
|
||||
]
|
||||
|
||||
const router = createRouter( {
|
||||
history: createWebHistory(),
|
||||
routes: routes
|
||||
})
|
||||
|
||||
export default router
|
||||
@ -0,0 +1,27 @@
|
||||
<template>
|
||||
<div class="about">
|
||||
<p>
|
||||
|
||||
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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The question then becomes: can we make use of these backdoors to infiltrate programming practices and open more entry points from within?
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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.
|
||||
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
|
||||
</div>
|
||||
</template>
|
||||
@ -0,0 +1,28 @@
|
||||
<template>
|
||||
|
||||
<div class="intro">
|
||||
|
||||
<p>
|
||||
Hello Worlding is a network of pathways to walk through different ways to read, write and think with code documentation.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
<Pathways :pathways="pathways"></Pathways>
|
||||
|
||||
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
|
||||
import Pathways from '@/components/Pathways.vue'
|
||||
import pathways from '@/assets/pathways.json'
|
||||
|
||||
|
||||
|
||||
|
||||
</script>
|
||||
@ -0,0 +1,57 @@
|
||||
<template>
|
||||
<h1>{{title}}</h1>
|
||||
<div class="description">
|
||||
|
||||
<p v-for="section in description" :key="section">
|
||||
{{section}}
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
<dl v-if="readmes">
|
||||
<div class="readme" v-for="readme in readmes" :key="readme.title">
|
||||
<dt>
|
||||
<a :href="readme.where">
|
||||
{{readme.title}}
|
||||
</a>
|
||||
</dt>
|
||||
<dd>
|
||||
<p v-for="section in readme.what" :key="section">
|
||||
{{section}}
|
||||
</p>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
</dl>
|
||||
|
||||
</template>
|
||||
<script setup>
|
||||
|
||||
import {ref, computed, onMounted} from 'vue'
|
||||
import {useRoute} from 'vue-router'
|
||||
|
||||
const route = useRoute()
|
||||
|
||||
const title = ref('')
|
||||
const description = ref('')
|
||||
const readmes = ref(null)
|
||||
|
||||
|
||||
onMounted(async ()=>{
|
||||
|
||||
const data = await fetch(`/pathways/${route.params.slug}.json`).then(res=>res.json())
|
||||
|
||||
console.log(data)
|
||||
|
||||
title.value = Object.values(data)[0].title
|
||||
description.value = Object.values(data)[0].description
|
||||
readmes.value = Object.entries(data).slice(1).map(([title, entry])=>{
|
||||
return {title, ...entry}
|
||||
})
|
||||
|
||||
|
||||
})
|
||||
|
||||
|
||||
</script>
|
||||
<style></style>
|
||||
@ -1,7 +1,13 @@
|
||||
import {fileURLToPath, URL} from 'node:url'
|
||||
import { defineConfig } from 'vite'
|
||||
import vue from '@vitejs/plugin-vue'
|
||||
|
||||
// https://vitejs.dev/config/
|
||||
export default defineConfig({
|
||||
plugins: [vue()],
|
||||
resolve: {
|
||||
alias: {
|
||||
'@': fileURLToPath(new URL('./src', import.meta.url))
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
Loading…
Reference in New Issue