Design Doc
Source Code
Live Builds

Tool Making Follow-Up: What I Mean by Friction


Your comments on my last blog post made me realize that I did a bad job explaining myself. This commenter put it nicest:

It sounds like you have a much broader definition of “friction” than I initially thought from your blog post. I understood friction to be the time spent bending tools to your will - the times when your IDE slows you down rather than speeding you up, when Git needs you to spend time merging code that it should have handled seamlessly, etc.

If you can provide some more insight into the types of friction you’re looking to eliminate (or even some examples) maybe it would help us to understand why you think rebuilding the tools will be worth it. This seems like a case where you’ve reached an obvious conclusion that makes little sense to us because you have so much more information than us.

Freedo50’s comment

First, I really appreciate you giving me the benefit of doubt and expressing your difference in understanding so carefully.

You’re completely right that I did a bad job of explaining the kinds of frictions I mean. The frictions you describe (mostly stuff that takes annoying amounts of time) exist, but they don’t bother me too much. And I am explicitly not talking about the frictions of the particular technologies I chose - those were trade offs that I’m very happy with so far.

The frictions that I mean are much more systemic. The best way to illustrate them is maybe to describe my workflow and tools and then show you where I face obstacles:

  1. Many aspects of Citybound are incredibly complex, so I often start by doing extensive research, collecting relevant papers, blog posts etc. and taking notes from them. I’m using Notion for that now, which is the first tool that I found (and I looked a lot) that handles both research reference databases and freeform note taking well.
  2. When sketching out ideas for my own implementation, I like to literally sketch them out, even if I’m working on something very abstract - I’m a very visual thinker. I’m using an iPad Pro with pencil and the Concepts technical drawing app, which is the first app that feels better than good old paper (again I looked a lot). No idea why it took that long to exist. Drawing in there is a breeze, but then the problems start...
  3. Now I want to combine my drawings and my free form notes, but I can’t embed a live version of my Concepts drawing in my Notion notes. I can only export the drawing as a static picture and then embed that. But then I need to re-export and re-embed it every time I change the drawing, which I would like to do a lot. Friction threshold too high. So what ends up happening is that I have a disconnected mess of drawings on my iPad that are only linked to the corresponding notes in my head. Who knows how much I have already forgotten because of this.
  4. Fine. I have a rough plan, I want to start experimenting with code. The best way to do that is to have some small example test cases to see if anything works before having to integrate it with all of Citybound. Often I already have a lot of test cases in my drawings and bits from earlier. But I can’t visually embed those into my experimental code to guide me through writing the tests. And I will want to cross reference them again when trying to interpret failed tests or any other kind of unexpected behavior. Not easy. Friction threshold too high. I end up writing far fewer tests and debug more “in production” - after integrating with the rest of the game. The old gamedev tradition of “the game is my test” - it’s a disaster.
  5. Now I’m debugging my code. Step debuggers are great, except that they only display my game objects as raw data. For small objects that’s fine, but for complicated objects with lots of connections to other objects (basically everything in Citybound) it’s like flying in the fog without instruments. Why can’t I define how the debugger should visually represent my game objects, so they make sense and are more explorable. Not possible. Friction too high. I end up debugging by guessing, which works eventually, but often takes 100x longer than if I could just clearly inspect what’s going on.
  6. Somehow I managed to come up with something that kind of works. (The prototypes are proof that that does happen). Now I probably want to tell you about it. Or I want to remind myself half a year later why I did this and how. I want to see a relevant mix of free-form notes, drawings and code, all next to each other. Not possible. Friction too high. I have to hope that I linked notes in code and switch between them. And I have to hope that those of you intrigued by my notes will somehow find the relevant code hidden somewhere - the first huge obstacle to contribution.
  7. Sometimes even more important than the notes or drawings or code itself is how they evolved over time. I want to see a full history with visual time travel of all of these artefacts. Sure, code has git, but that is far from ergonomic to explore and tracks “differences in files and text” rather than logical steps of project evolution. Better hope I at least have good commit messages! My notes have per-note history, but only I can see that. Drawings don’t have history. And all three of them are still disconnected. Friction too high. I often have to retrace my steps by hand, and those following my project have to accept my code and notes as an end result that fell from the heavens.
  8. The most interested of you want to follow the project and my progress and comment on it. Probably there are some parts that each of you is particularly interested in. You could subscribe to all of my code commits and get a firehose of only the most technical steps. You could hope that I write a blog post, but I only write those on the most overarching topics, because that, too, takes a lot of work. Maybe you will find a random comment of me on Reddit. Or on GitHub issues. I try my best to actually answer all questions and comments everywhere, because I want to reach everyone, lacking the tools to channel people with similar interests to the most relevant place in my notes+drawings+code mix, where ideally they could just comment directly. And ideally their comments would become a natural part of the overall project history structure. Your ideas are very important to me and often influence my design, so they should be within my “mental field of vision” as well, whenever I work on something relevant.

I hope this expansion made things more concrete!

I apparently also made the mistake of sounding like I want to build better tools completely from scratch:

I’m not saying don’t be ambitious and I’m certainly not saying don’t believe in yourself. I’m just pointing out that the collective thousands of hours that are poured into tools like Git, Wordpress, IDEs, programming languages etc. by communities and companies of thousands of people are basically insurmountable for one man wanting to replace ALL of them with something better.

Freedo50’s other comment

You are of course right, but I am not aiming to rebuild all those things from scratch, but to build on top of them whenever I can. It’s still too early to talk about how I want to improve code editors, but I’m pretty sure I will build something on top of Monaco, the open source editor “engine” of VS Code. Like that, I get syntax highlighting and even autocomplete for many languages for free. My plans are too ambitious for just a VS Code plugin (which some of you suggested), hence the inverse route.

I will have my own simple collaboration model, but I’m fairly certain it will interoperate with git.

For whatever exists in the software world that my tools imitate or need to talk to, I will try to reuse as much existing work as possible, and maximize for interoperability everywhere I’m doing my own thing.

I hope all that clears things up and makes my plans look more like a good idea for Citybound. I’m happy to discuss it further with you!

→ Discussion on /r/Citybound