I can already draw pictures and text using this really lousy markup language. Perhaps I should just go write a bunch of webpages in it.
And maybe throw in "how to program" for good measure.
Basically the motivation for this comes from a chessboard app I built over the past week. It started out on Carousel but grew too large (~500 LoC) to edit ergonomically on a single screen on the phone. (And if it's a lousy experience, why bother sharing it?)
I could make it a "Carousel app" rather than just a screen (like this little example and my Sokoban app) and that would at least split up the code between multiple screens so the scrollbar isn't too tiny to acquire. But it still wouldn't be a great reading experience. The program is a hairball. There isn't a clean way to split up the core into files in a way that makes it obvious where to look for any given function. And Carousel doesn't yet have a way to search over all screens.
In the end I made it just a bare LÖVE app. None of my frameworks seemed to add value in this case. But it did get me thinking about how I would lay the program out if I had more creative freedom in Carousel. Conveying the big picture of programs is something I have cared about for a long time.
I think the first thing I'd want to say is:
The app is a place to play chess. So it has a chessboard and a chess clock. The app consists of 2 screens. First you set the time for the game. Then you play. The only variables shared between the two screens are start_time and increment.
This picture doesn't have space for details, but imagine we click into the “Set timer screen” box.
I think there's one more level of detail I want to show before I get into raw/intimidating code. The key thing to look for in this screen is the exit where it heads to the main screen of the chessboard. Everything else is towards that purpose.
(I'm trying here to follow a pattern Christopher Alexander calls "Strong centers." When something is important, you put it within a succession of boundaries to draw the eye toward it.)
At this point if you click on the “Set timer screen” a second time, it seems sufficient to show you the code (140 lines). It's still not easy to read, but past a point I think there's some irreducible difficulty in reading code, and we shouldn't pretend otherwise.
The other side would have a similar experience. A few simple pictures to establish relationships and key variables, and then you get thrown into code.
To set up this experience I think I'd need to add two things: