Writing about writing about programming(axleos.com)
axleos.com
Writing about writing about programming
https://axleos.com/writing-about-writing-about-programming/
9 comments
This is great! I really enjoyed the interactivity of it all. I’ve been working on building similar, but much simpler, tools to help me blog and seeing this is inspiring.
Good job!
Good job!
A few questions/notes from reading the post and looking at the repo:
1. Is the post trailing the repo, or vice-versa? This line in the README describes a different command format and seems to suggest that {{}} caused trouble? https://github.com/codyd51/penpal/blob/4ff061b045aa447ac8976...
2. Some of the code blocks, like the first `src/main.rs` block, link to divergent GH source. Is that coming from penpal in some way, or are you grafting that back on after somehow? (And if it's built in, is there a way to avoid/manage this divergence?)
3. The post and repo contradict on what `generate` does, and the post lets us dangle for a really long time before resolving it.
The post says: "Let’s generate an executable representing our (tiny!) source tree so far." (and then shows a single-line code block with `{{generate}}`)
The repo says: "When the `generate` command is used, the current state of every snippet is rendered into a source code tree."
The last section of the article finally clarifies, but it'd be kind to be clear that generate creates only the source tree and note that you're grafting on a compile step separately that's outside of penpal's scope.
1. Is the post trailing the repo, or vice-versa? This line in the README describes a different command format and seems to suggest that {{}} caused trouble? https://github.com/codyd51/penpal/blob/4ff061b045aa447ac8976...
2. Some of the code blocks, like the first `src/main.rs` block, link to divergent GH source. Is that coming from penpal in some way, or are you grafting that back on after somehow? (And if it's built in, is there a way to avoid/manage this divergence?)
3. The post and repo contradict on what `generate` does, and the post lets us dangle for a really long time before resolving it.
The post says: "Let’s generate an executable representing our (tiny!) source tree so far." (and then shows a single-line code block with `{{generate}}`)
The repo says: "When the `generate` command is used, the current state of every snippet is rendered into a source code tree."
The last section of the article finally clarifies, but it'd be kind to be clear that generate creates only the source tree and note that you're grafting on a compile step separately that's outside of penpal's scope.
You're right, thank you for the thoughtful feedback. It's true that the blog post skims over the meaning of `generate` when introducing it, and that I'm doing a bit of extra work under the covers in this post. I thought keeping things light and interactive would help easing into the details, but it's true that the reader has to wait quite a long time to see what the preprocessor is doing exactly, and it's not clear until the end what exactly is going on. I'll add something in to signpost this a bit better.
To answer your questions, the post is trailing the repo. I've uploaded the full source comprising this post here: https://github.com/codyd51/penpal-blog-post-preprocessed.
The code blocks link back to the Github source via a custom Hugo shortcode, and I currently need to maintain this by hand. While wrapping up this blog post, I added support for generating this shortcode via an extension to the `show` command.
Here's what the penpal command to render a hotlinked code block looks like, in the source code of this blog post: https://github.com/codyd51/penpal-blog-post-preprocessed/blo...
Here's what the shortcode generation for this looks like in penpal: https://github.com/codyd51/penpal/blob/release/penpal/render...
I think it'd be really nice to maintain all of this automagically - it seems reasonable that the technical content being built up would frequently be hosted in a finished state somewhere!
To answer your questions, the post is trailing the repo. I've uploaded the full source comprising this post here: https://github.com/codyd51/penpal-blog-post-preprocessed.
The code blocks link back to the Github source via a custom Hugo shortcode, and I currently need to maintain this by hand. While wrapping up this blog post, I added support for generating this shortcode via an extension to the `show` command.
Here's what the penpal command to render a hotlinked code block looks like, in the source code of this blog post: https://github.com/codyd51/penpal-blog-post-preprocessed/blo...
Here's what the shortcode generation for this looks like in penpal: https://github.com/codyd51/penpal/blob/release/penpal/render...
I think it'd be really nice to maintain all of this automagically - it seems reasonable that the technical content being built up would frequently be hosted in a finished state somewhere!
Thanks for the extra context.
Nothing wrong with deferring unnecessary detail! The word "executable" implied it was also compiling, and that surprise sent me out from the text to confirm I was understanding (since I hadn't seen any hint that you were telling it how to do so).
Anticipating the question should (imo) be enough.
It's a tricky corner that could definitely use better tooling. I mentioned my own make-based solution in another comment, and it's definitely something I keep having to iterate on as I spot different needs.
Nothing wrong with deferring unnecessary detail! The word "executable" implied it was also compiling, and that surprise sent me out from the text to confirm I was understanding (since I hadn't seen any hint that you were telling it how to do so).
Anticipating the question should (imo) be enough.
It's a tricky corner that could definitely use better tooling. I mentioned my own make-based solution in another comment, and it's definitely something I keep having to iterate on as I spot different needs.
I made a tool to help motivate me write every day. After sharing it with some writers for their feedback, one of them had a really insightful comment: “Wow, wanna-be writers will really do anything to avoid writing!” I had spent a lot of time writing a tool to help me write when I could have been writing instead! Writing is an ancient technology. We more or less know how to do it efficiently. I think it’s important to ask ourselves why we spend time writing tools to write.
I remember when I was a kid, writing an essay on a laptop for the first time, and realizing that the reason the page was blank was because I had nothing to say.
At the end of the day, writing isn't scratching graphite onto paper. It's putting ideas into words, and it's the ideas part that form the main bottleneck for me.
As it turns out, having interesting life experiences and or insightful analysis is hard. The former can only be gained by doing stuff in the real world, while the latter can only be gained by staring at a blank page really hard for a while, and or flashes of insight that seem almost random to me.
Writing is thinking. Programming is thinking. Thinking is hard. Procrastination is easy.
I find what helps is to keep a notebook. Ideas come. I jot them down before they disappear. Now I have much more to say, much more work to do, and procrastination is still easy, but at least that's one problem ameliorated.
At the end of the day, writing isn't scratching graphite onto paper. It's putting ideas into words, and it's the ideas part that form the main bottleneck for me.
As it turns out, having interesting life experiences and or insightful analysis is hard. The former can only be gained by doing stuff in the real world, while the latter can only be gained by staring at a blank page really hard for a while, and or flashes of insight that seem almost random to me.
Writing is thinking. Programming is thinking. Thinking is hard. Procrastination is easy.
I find what helps is to keep a notebook. Ideas come. I jot them down before they disappear. Now I have much more to say, much more work to do, and procrastination is still easy, but at least that's one problem ameliorated.
Writing about writing about writing about programming
Interesting to see how the writer scratches this itch.
I've been managing the same basic friction with multiple incremental copies of the source files, a little shell script to generate diffs/logs/artifacts, and some make-based tooling to re-run those when sources change (and sync the outputs to a gist so that I can optionally include an instruction for obtaining the source via git). It works, but it's obviously suboptimal if I goof something and then have to make the same fix several times.
I've been managing the same basic friction with multiple incremental copies of the source files, a little shell script to generate diffs/logs/artifacts, and some make-based tooling to re-run those when sources change (and sync the outputs to a gist so that I can optionally include an instruction for obtaining the source via git). It works, but it's obviously suboptimal if I goof something and then have to make the same fix several times.
This post is ostensibly about some tooling I’ve written to help me write posts that contain lots of code, while ensuring that the code always produces a valid source tree which matches up with where we are in the prose. This is easy when a post is small, but can become really difficult to manage with a larger piece of work!
The bulk of this post, though, is a proof-by-demonstration of the tooling. We implement a little 2048 clone, line by paragraph, and there’s a bunch of checkpoints interspersed throughout the post - and now we’ve implemented input handling! and now we can slide tiles around!
At each of these checkpoints, I’ve embedded some live visualizations of the code we’ve written so far. My hope is that the reader can really get a feel for what we’ve built so far, because they can see what works, and what doesn’t work, running right in front of them in the browser. These little computers are taken from snapshots produced by the tooling, compiled to Wasm and executing in the browser.
This is my first time providing this level of interactivity in one of my posts, so please do feel welcome to play around with it. I’d love any and all feedback on the experience. Thanks so much!