Gli obiettivi strategici si trovano al mercato dei sogni
This place is our land of truth and illusion. In this repository we want to keep everything that doesn't deserve its own repo (e.g. website, large codebase, etc). Here you'll find discussions, configurations, designs and specs of what we do.
We don't have many rules or constraints, but we try to follow some principles:
- we're a project heavily based in Italy, so Italian is a language you can use, especially in discussions there's nothing wrong with writing designs and proposals in Italian
- we hope to get everything done in the shortest time possible and get back to other leisure activities, so AI and vibe coding are welcome, but remember that people still need to be able to read what you write
- we try to have at least one review for every change, we don't need fancy automation, but we try, even informally, to get our changes reviewed
- a north star that can guide you when working on this repository is that our intention is to make this work as public as possible. we might not manage to do all development and discussions truly "in the public", but at least we try to write with that intention
Design documents are a nice thing that tries to put intentions for present and future in writing, for us they're nothing more than documents written in markdown that allow us to have:
- documentation for whoever wants to edit/play with/reproduce our infrastructure
- a transparent way to share decisions internally and allow us to follow technical developments even in areas we're not directly involved in can be used as a decision-making tool for technical matters
- implicitly it's a way to have a history and justification of our activities and research, which can be very useful when it comes to applying for grants
Some important guidelines:
- our repository is on github, but even if it were elsewhere we don't delegate our trust to some contraption anyway... (watch what you write)
- the most important thing is to be able to know tomorrow why we made a choice today (e.g. to avoid cursing too much later)
- your goal is to convince yourself and your peers that your plan is the best option
So please, if you want to make a proposal prepare a PR creating a document
in the design folder and number it to allow chronological ordering: e.g.
0001-technodomination.md.
Starting from this post we came up with an idea for sections to divide the document into.
- authors/owners: no, for now git is our friend and we need an explicit reference to who's the point of contact for a design, we're few enough to handle it between git and informality
- summary: without going crazy
- context/background/origin: where did this need come from? a bug, saving money, cryptoquantum parthenogenesis?
- goals/non goals: the second almost more important than the first, we want first and foremost to prevent bad things from happening
- proposal/design: anything goes here trying to keep in mind that in an ideal world this could be published as a technical article (how to, wiki, blog, etc)
- alternatives: in a world of extremely opinionated people it's fundamental to say why you didn't choose something, it's perfectly fine to say you didn't feel like it, but this is the section that will be used the most by whoever comes after you and will wonder after four beers: "but why did they choose the wrong side of history?" It's your chance to set up "I told you so."
- even cheap IA is good in generate mermaid graphics from a bulletpoint