Tools for Online Speech logo
by Jacob O'Bryant

Jacob O'Bryant's Newsletter

Yesterday I published How to edit S-expressions in Vim without plugins. It gives a quick demo of some lesser-known Vim features that make editing Clojure easy. I wrote this because I’d never seen anyone talk about those features before—all the Vim + Clojure posts I could find just talked about plugins like vim-sexp and parinfer. I think that makes things overly complicated for people new to Clojure.

Now, there’s a separate question of if you should continue to edit Clojure with Vim in this way, without plugins for structural editing. That’s what I do myself, and it seems to work well enough. But some people are vehemently opposed to that kind of thing, and it’s not a very important argument anyway. I’m focused on the case of new Clojurists, who I think absolutely should be able to get started without learning structural editing.


I’ve made a handful of tweaks, like adding more description to the landing page. There’ve been 12 active users for two weeks in a row, and this week we’re at 9 so far—just a few more and we’ll have growth again.

Clojure guide

After posting Mystery Cows last week, I’ve been taking some time to think about the best approach to writing this guide. I do think it’s been more effective to write all the code for a given project first and then add it to the guide. The trick is figuring out how to do things in a way that takes the least effort from me but helps the most people—which is nuanced because different people need different levels of help. Some people just need an example codebase they can dig into and see how the parts are stitched together. Some people need detailed step-by-step instructions. The nice thing about teaching with example projects is that people who just need the code can skip the tutorials and just go to the repository.

So I’m thinking about following these steps:

  1. Write all the code for a project. In the Readme, include documentation for developing and deploying the existing code base on your own.

  2. Write a code walkthrough. Give links to various code files in a particular order and give high-level explanations.

  3. Compile a list of resources (articles and videos mainly) that teach the skills needed to implement the project.

  4. Write a series of documents that demonstrate how to implement the project a piece at a time. Readers can try to implement each step on their own first, but then they can reference the code and tutorial for that step if needed.

Then I can just repeat these steps for multiple projects. I’d have a “course” document that links to each of the relevant projects. It would contain the resources from step #3 that are common to multiple projects.

It might be useful to have some projects that omit the step-by-step tutorials. Research shows that students often work harder to figure out things on their own if there’s not a solution readily available. So having a mix of projects with and without solutions might be best—perhaps I’d even just give project descriptions and demonstrations without making any code available.

Anyway, I’d like to repeat that process for three courses: frontend, full-stack and core language. The latter would probably consist of simple terminal games, like tic-tac-toe.

Published 31 Mar 2020

I write an occasional newsletter
about my work and ideas.

RSS feed · Archive

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.