My Project Cards Were Getting Ahead of My Projects

The projects on raioviajante.com are not all the same kind of real.

Some are working software.

Some are experiments.

Some have code, a direction and a large amount of empty space between the two.

Some mostly exist as design work and the stubborn belief that I will eventually build the rest.

I am fine with that.

The project cards were having a slightly harder time admitting it.

01.One sentence can skip a lot of work

A project card has very little room.

It needs a name, a short description and enough context for somebody to understand why the thing is there.

That compression makes it extremely easy to write about the destination instead of the current location.

I know what I want the project to become. I have probably written plans for it, opened issues and imagined the version where all the interesting parts work.

So the compact description arrives naturally:

A tool that does all of these useful things.

Meanwhile, the repository may contain the first two of those things, a document describing the third and a very optimistic milestone for everything else.

The sentence is not exactly a lie.

It is more like the present tense got ahead of the implementation.

That started bothering me while I was revisiting the metadata on the root site.

The site was supposed to show what I am actually building. In a few places, it was doing a better job of showing what I intended to have built later.

01.1Everything wants to sound finished

There is a strange pressure around developer projects to make every repository look deliberate and complete.

The README needs a confident description.

The project card needs a clean sentence.

The feature list quietly mixes working behavior with future direction because five bullets look more substantial than two.

Even a learning project starts sounding like a product announcement if I remove enough uncertainty from the wording.

I understand the temptation.

“I am experimenting with this and several important parts do not exist yet” is not the strongest possible sales pitch.

But I am not selling most of these things.

I am trying to keep a useful record of work that is at very different stages.

Making an unfinished project sound finished does not make the project better. It just makes the website less accurate.

It also removes the interesting part.

Orbit being a scheduler that already schedules things would sound more impressive than Orbit being a project where I have modeled executions before implementing the scheduler.

The second description is true.

It is also a much better explanation of why I am building it.

01.2Let unfinished things look unfinished

I have been correcting the project metadata with a simpler rule.

If something is an experiment, call it an experiment.

If it is mostly a design, do not borrow verbs from the future implementation.

If one part works and another part is planned, keep those statements separate.

This does not mean adding a warning label to every unfinished repository.

It means letting the current state be enough.

The root site already describes projects as “things that survived long enough to deserve a name.”

Surviving long enough to deserve a name is not the same as being done.

That is useful because almost nothing I care about building is done in the permanent sense anyway. Sweep can organize more kinds of files. Orbit can eventually run the executions it models. Yanawa has an entire compiler-shaped problem waiting for it.

The site does not need to pretend otherwise.

I still want the descriptions to be concise.

I still want the projects to sound interesting when they are interesting.

I just do not want a card to cross the gap between intention and implementation on the project's behalf.

The code can get there first.