Prose And Code And The Difficulty Of Learning

January, 2023


Reading is hard for me. I forget the diagnosis. It's like dyslexia. All I remember is years spent with a tutor learning mental gymnastics to deal with it. It happens in the background now, but it's always there. Always taking energy.

Learning to code is work. Sometimes, it's smooth. Mostly, it's finding a reserve of focus and putting your shoulder into it. That focus takes energy to activate and energy to sustain. Breaking it means starting two steps back. Run out of it, and you're done.

Those factors collide whenever I'm working on something new. Lately, that's Rust. And, an example of getting my ass kicked is the second chapter of The Rust Book. It's a single page that's very long and has a very high ratio of prose to code.

A Bird's Eye View

Here's what it looks like. The column on the left is the full page with the code highlighted in green and a blue section for the final version. The column on the right mushes the parts together with the black section representing the text, green for the code, and blue for the final version again.

A display of the percent of code in two columns for a page on the Rust Book site


I can't make it through that. There's roughly six times as much prose as there is code. That's too much for me. It wears me out.

When I'm first learning a thing, I don't need to know so much of the "why". Just tell me what to do and I'll do it. Add the context later. That way I'm not trying to learn "what" and "why" at the same time.

I'm more sensitive than most to this. I can't help but wonder though, would folks without learning disabilities be served by a more streamlined editorial in the early stages? My guess is yes. At a minimum, it's something worthy of research.


  • Please point me to any resources you have that discuss this kind of content ratio. I do my code write-ups with as tight an edit as I can manage because that's what I like. If most folks are better off with something more like that page from the Rust book I'd like to know. (I'll probably still write the same way since I'm sure there are other folks who have the same difficulties as me, but I'd like to have the information as an option to act on)

  • The Rust Book looks incredible. It's just heavier that I can easily deal with. I've been going through Rust Adventure and I can process the videos much easier. Some of that is the difference between video and text, but it also has to do with the refinement of information down to more what you need to know at the time vs a full suite of context. I can process that a lot better. (Full disclosure: I know Chris who runs the site.)

  • I'll eventually work my way through The Rust Book and write up my version of notes on it that'll be a lot smaller. I'm also looking at Rustlings.

  • An example of something that's a lot easier for me to process is Typography For Lawyers. I got turned onto it from the ShopTalk Show Discord. The home page freaked me out a little with so many links, but the site is designed like a book that you click through and read page to page. Each one of which is a digestible size. (I could do with them being even shorter, but for the most part I don't have any problem making it through them)

  • That navigation for the Typography For Lawyers site is interesting too. It feels like editing the Rust Book example to be multiple pages would go a long way towards making things better even without changing the text. I'm not sure about that, but the little break and reset from other sites has worked for me. I've even experimented with that and some Emacs Org Mode text. That was also about keeping track of how far you've read, but the individual pages feels nice.

  • I should throw out the two books that got me started in programming: Learning Perl and The Perl Cookbook. The approach of those two books combined got me up and running in with no prior experience. Finding that feeling and reproducing it for others is what I'm after.