intermediate_ruby     about     articles

Jekyll Bug Fix with Matt Series Index

Part 0 Table of Contents

Why This Series Exists #

A few weeks ago, I sent out this tweet:

I ended up connecting with Matt Swanson, and he thought my plan was interesting, and was willing to help me out.

Matt Swanson is brilliant. He’s behind Boring Rails, and has forgotten more about Ruby, Rails, and software development than I'll ever know I currently know.

I hope to someday learn more than he’s forgotten. 🤞

Before we started, Matt suggested this Jekyll github issue to work on: slugify replaces Tamil vowel marks with hyphen #7973

We finished with this pull request: Switch slugify regex to support more Unicode character groups #8167

I recorded the whole session, which was two hours, end-to-end, from

how Matt found this particular issue


writing a test that fails, making it green, refactoring, and then making/submitting the pull request.

I learned a lot, and more importantly, there was a lot of information that we covered as we worked through this fix of a real-world problem that would be of great value to early-career software developers, specifically tacit knowledge.

I’m editing it down, optimizing for moving quickly through what we did, to show all of the thought process and to highlight as much of the tacit knowledge as possible.

What is Tacit Knowledge #

Cedric Chin wrote something recently that gave me language for a phenomina I’d felt for years but never figured out how to say directly.

Quoting from his piece Why Tacit Knowledge is More Important Than Deliberate Practice

Tacit knowledge is knowledge that cannot be captured through words alone.

He goes on to say:

…[T]acit knowledge does exist, and understanding that it does exist is one of the most useful things you can have happen to you.

Once you understand that tacit knowledge exists, you will begin to see that big parts of any skill tree is tacit in nature, which means that you can go hunting for it, which in turn means you can start to ask the really useful question when it comes to expertise, which is: that person has it; that person is really good at it; how can I have it too?

This tacit knowledge stands in contrast with transmissionism. There are communities of people, lets call them “transmissionists”, who think that all knowledge one can obtain or need can be communicated directly, explicitely, in a book or a lecture.

Cedric explains transmissionism thusly:

In pedagogy, this is known as ‘transmissionism’, and it is regarded amongst serious educators with the same sort of derision you and I might have about flat-earth theories today.

It goes something like this: some people believe that it is possible to teach technique by explaining things to others. They think that if you can find just the right combinations of words with the right sorts of analogies; if you can really break things down into the right level of atomic details, things will magically click in their students’s heads and [the students] will succeed.

Such people have likely never attempted to do so in a serious manner.

I’ve spent hundreds of hours over the last few months (and years!) helping less experienced software developers learn their craft.

Over and over again, I’ve seen the truth of this statement.

It’s completely impossible to impart useful knowledge by stating it - the individual learning the knowledge has to do it themselves. They have to drill it, practice it, make mistakes, explore the problem space, and pattern-match on examples from those who have gone before.

Cedric, again:

In other words, tacit knowledge instruction happens through things like imitation, emulation, and apprenticeship. You learn by copying what the master does, blindly, until you internalise the principles behind the actions.

So, I wanted to systematically start copying the masters, and I want to help others do the same.

Studying the finished product is only part of the solution #

Over the years, I’ve tried different tacts, like rebuilding portions of the Rake gem, to practice writing ruby in the style of experts.

This approach didn’t bear much fruit, as software is not written in such a linear fashion. I tried to rebuild a class from scratch, top-to-bottom, using tests as a guide. This approach doesn’t model the actual iterative nature of software development.

Next, I thought I’d investigate pull requests, and practice building the equivalent code myself. This also came up short, as it didn’t let me directly inspect the process that lead to that pull request.

Eventually, I concluded that one of the most effective ways of learning is to observing expert practitioners doing their job.

This observation-based learning comes with two additional challenges.

Challenge One

First, if the expert is navigating a codebase/application that they are deeply familiar with, and I have no familiarity with, I’ll just be lost the whole time.

How much of their effectiveness is related to knowledge of the codebase, vs. knowledge of generalized principles of software development?

I needed to observe an expert who had knowledge of the codebase equal to my own. Since I know nothing about most codebases in the world, that meant myself and the expert had to approach the same codebase with zero (or near-zero) prior knowledge.

Challenge Two

Second, assuming we both approach the codebase with zero prior knowledge, it won’t be long before the expert does something that I don’t understand. Even if I understand all the code they’re writing, what if they investigated some portion of the codebase, and I didn’t understand why that portion of the codebase was of interest to them?

I needed to inject myself into the process, so when the expert does something I didn’t understand, I could stop them and say

Why did you do that?

This video/companion blog post “format” is a good way to highlight tacit knowledge #

These constraints have led directly to this project.

I’m working on a few different types of resources, but most of the work I’ll do here will be pairing with experts to observe them at work, in a way where I can ask them to explain why they did something when their decisions deviate from my understanding.

And I will do all of this in a way that can be shared with others.

Why other formats for transferring knowledge don’t quite meet my needs #

You would be well justified in expressing some skepticism here.

Josh, there are entire shelves of books, written by absolute experts who are good at teaching others about all of this. Courses, blog posts, conference talks, etc. Are you really telling me all of that isn’t effective?

All of those resources are effective! I’m glad they exist, and I will continue to make use of them for my own learning.

Cedric Chin linked to Why books don’t work, and I’d recommend you click through and give it a read. Books, lectures, and textbooks all have a role to play, but are substantially less effective at transferring knowledge than nearly everyone recognizes.

But all of these resources have the same problem. They are resources about work, but they are not resources of doing the work.

Steven Shorrock wrote a piece called The Varieties of Human Work, in which he outlines four varieties of human work:

  • Work-as-imagined
  • Work-as-prescribed
  • Work-as-disclosed
  • Work-as-done

varieties of work

You’ll notice that “work-as-done” is very difficult to learn about as a non-practitioner, because you would rely upon someone disclosing their work to you, to learn anything about it.

By definition, every piece of knowledge that comes from a book, blog post, course, conference talk, or conversation is coming from the work-as-disclosed category. I don’t mean to imply that the creator of that resource intends to mislead! Far from it! I simply mean that the work-as-disclosed necessarily deviates from work-as-done, and I want to directly inspect the work-as-done category.

Remember Cedric’s earlier discussion of tacit knowledge?

Tacit knowledge is knowledge that cannot be captured through words alone.

Which means I cannot rely exclusively on stated knowledge from senior developers. I simply must observe them working in order to observe their use of tacit knowledge.

And that’s why this series of videos exists.

To get started, jump over to part 1:

But before you go, why not subscribe to get updates when more guides in this series are done, as well as when future guides go up?