Some example scenarios I’ve run into where a bench voltage divider comes in handy include:

• Reducing a line-level signal from volts to millivolts to simulate input from a phono cartridge.
• Reducing a 10V reference to calibration levels like 3V or 300mV.

Rather than building up a janky breadboard divider every time, a few years ago, I built a simple point-to-point set of dividers with a rotary switch and a surplus pedal enclosure.

This is pretty okay and gets the job done, but it’s not very precise. Using close-enough standard resistor values only gets in the general vicinity of the target voltage. I wanted something equally convenient and repeatable, but far more precise.

Getting more precise means matching target shunt resistance values within a few ohms. That requires at least the ability to get within a few hundred ohms with one or two standard resistors, then trim out the remainder with a small trimmer potentiometer. And that really calls for a PCB…

The Switchable Voltage Divider PCB

So I fired up Kicad and quickly designed a PCB that implements a switchable resistive voltage divider, each divider tap producing a fixed ratio of the input voltage based on up to two resistors and a trim potentiometer.

Actually there are two PCB designs. The first proof of concept design provided six different resistor-trim-resistor taps. It had no direct switching on board, just taps that could be connected to an external switch. This board was also a bit bigger, probably more suited to a 1590 series or larger enclosure.

The second design is the one highlighted here. It’s smaller, intended to fit in a standard 125B enclosure. It has five separate voltage dividers and pads to fit a 1-pole 5-position rotary switch.

The PCB is designed around a 1-pole 5-position rotary switch (using a 1-pole 8-position form factor) like the ones available from pedal parts supplier Love My Switches or PedalPCB. Each tap has space for two resistors and a trim pot (Bourns 3362P footprint).

The board is sized to fit within the enclosure with room to install your choice of inputs and outputs (banana jacks, RCA, etc.).

To summarize the BOM I’m using:

• Five Bourns 3362P or equivalent trim potentiometers
• 1-pole 5-position rotary switch (see links above)
• Resistors per your divider details (see below)
• Input and output jacks (your choice)

If you want to build your own, I will have some for sale on eBay. If you are handy with PCB production, you can grab the Kicad or production (gerber) files from my GitHub repository.

Resistor Divider Details

Each tap on the PCB is a two-resistance voltage divider:

Vin ── Rtop ──┬── Vout
              |
           Rbottom
              |
             GND

Rtop (sometimes designated Rseries or R1) is a fixed value for all taps. I used a 100k resistor in this position that actually measures approximately 100,468 ohms.

Rbottom (sometimes designated Rshunt or R2) is implemented as:

• A fixed resistor
• A small trim potentiometer (Bourns 3362P)
• Optional second series resistor or jumper

This arrangement allows:

• Coarse ratio setting with fixed resistors
• Fine trimming with a low-value trimmer (I used 500 ohm)
• Good long-term stability by minimizing the trimmer’s contribution to total resistance

The rotary switch selects which divider output is routed to the output jack.

Divider Equation

The fundamental voltage divider relationship is:

Vout = Vin * (Rbottom / (Rtop + Rbottom))

To design a divider for a desired ratio:

k = Vout / Vin

Solve for the shunt resistor:

Rbottom = (k / (1 - k)) * Rtop

Example Divider Values

Exact values matter. Let’s say Rtop = 100,468 ohms.

In practice, these are realized using nearby standard values plus the trim pot to dial in the exact ratio.

You can, of course, use whatever ratios you like.

Voltage dividers are pretty straightforward, but it’s not always so simple. Sometimes you need to be aware of source and load impedance, measurement loading effects, power dissipation and self-heating in the resistors, tempcos and long-term stability, and other small but measurable errors, especially when you’re working with precision references or very low output voltages.

Build Notes

Here are some tips for a successful build.

1. Measure your series (Rtop) resistor as accurately as you can. Not everyone has a 6.5-digit multimeter to get the least significant digit. The trimmer gives you some wiggle room.
2. Do the math or use an online calculator to determine the values for shunt resistances (Rbottom) based on your actual Rtop value. DigiKey has a nice Voltage Divider Calculator.
3. Populate fixed resistors first. Use precision metal film resistors where possible. Keep resistor types consistent across all taps to improve ratio tempco matching.
4. Install the trimmer (Bourns 3362). Use the trimmer only for fine adjustment. Aim to keep it near mid-range once trimmed.
5. Install jumpers or series resistors: if a second resistor footprint is unused, install a jumper. Otherwise, use it to reduce the trim range and improve stability.
6. Trim each divider. Apply a stable input voltage. Measure Vin and Vout with the same DMM. Adjust the trimmer until the ratio matches the target value.

It’s a good practice to clean the PCB to thoroughly remove flux residue, especially around high ratios like the 0.01 tap.

Good luck!

I understand why “live coverage” news blogs are useful in some circumstances: incremental coverage of speeches or hearings or timely updates to a high-profile developing story. But live coverage or live update formats are abused for many other use cases and, in my opinion, they obstruct clarity.

There’s relevance for technical writing here, too. (Admittedly, it’s a stretch, but hear me out.)

Here are my hot takes on the ways the live news blog format fails to provide useful reporting:

• The format is backward. When I open the page, the most recent or specific details are at the top, and I have to read backward through the reporting. This is convenient for reporting, but it either assumes I’m following along from the beginning (who had time for that?) or wants me to scroll all the way to the bottom to catch up.
• Mixed-up topics. Live blogs work if the entire page is about incremental coverage of a single topic, but I frequently see the format abused as a conveyor belt of newly published, unrelated stories. Those unrelated topics in the middle of a live blog distract from the “developing story” and effectively bury the unrelated stories.
• If a story is worth reporting, give it the dignity of its own page and a headline in the appropriate section of the site. Make it discoverable outside of the live blog. Remember that users scan the front page and section page headlines to get a high-level read of the news.

CNN’s recent live coverage of the Firefly Blue Ghost lunar landing is an example of an okay use case (and execution) of the live blog format: Highlights: Firefly ‘Blue Ghost’ lunar lander touches down on the moon. It provides a straightforward link to the summary reporting but could use a better table of contents to provide a timeline and details of the reporting within the original content.

Here’s a pretty poor example from the Washington Post today: House tees up vote on censuring Rep. Al Green for disrupting Trump’s speech.

• The headline claims, “House tees up vote on censuring Rep. Al Green for disrupting Trump’s speech,” so I expect a tick-tock of house developments, but…
• The page’s content consists of capsule items summarizing (and linking to other stories about) federal real estate, proposed VA layoffs, the Department of Education, and DOGE. There’s just one item on censuring Rep. Green, but…
• If I were looking at the URL slug for context, I’d see “trump-presidency-news-speech,” which seems related to the president’s address to Congress but is completely unrelated to any of the items in the live blog.

Mostly, I want to complain about how annoying it is to read “Live News” reporting on the web. But there are lessons for technical communication as well.

• Order matters. Don’t assume prior knowledge or actions. If context or prerequisites are important, provide a table of contents or call out and link the necessary steps. If users land on a midpoint via, say, search, make it easy for them to get to the right starting point.
• Organization matters. Keep related topics together for easy browsing and discovery.
• Discoverability matters. Users infer a lot about your product and its usage patterns from a high-level view of your documentation.
• Blogs are great! They are an excellent format for publishing bite-size technical content as part of a marketing effort. However, make sure they link into your docs appropriately. Blog posts offer an easily shared and SEO-friendly way to invite users into more expansive experiences supported by guides and tutorials.

Make docs and news easy to follow and discoverable. Your readers will thank you.

So, to be fair, I should qualify my statement: AI will definitely replace some technical writers. But not all. Or even most.

Generative AI tools are already very good at writing, debugging, and documenting specific code modules. They are very good at summarizing text. They can identify and describe objects in images. They can search, analyze, manipulate, and translate text with high accuracy.

Generative AI tools are less good at creating novel new text artifacts at high quality without significant instruction and revision. And this is my point.

A modern AI model is trained on an enormous corpus of data. When you prompt an LLM, it generates an answer from mathematically contextual data in the model. Generally speaking, this makes it very good at creating useful content. When it has lots of useful context, it can simmer that context down into a response.

If it doesn’t have a useful context on which to draw — if it doesn’t know anything about the subject on which you’ve prompted it — the LLM can, at best, say it doesn’t know the answer. Or, at worst, make something up. Hallucinate.

It’s more complicated than that in action. There are methods for providing LLMs with additional context. Fine-tuning, embeddings, and RAG are methods for giving an existing model more information to work with. Agents and similar approaches give the LLM access to tools for finding or calculating additional information on the fly.

But the bottom line for all of these approaches is making sure the LLM has a broad context of relevant information from which it can generate an accurate, useful response.

If I want to create documentation or marketing copy for a unique new product, an LLM is of very limited use. It knows nothing about this new product — what it does, how it works, and which steps are needed to produce a useful result for the user. It has zero context for creating actually useful content.

Here’s where technical writers come back into the picture.

An experienced technical writer works with the experts on the team to understand the customer, their needs, and their expectations. What is the product meant to do, and what are the procedures to make it operate correctly? What external knowledge, tools, and information are needed? What types of content are most appropriate for customers? How do design guides and learning curricula with appropriate outcomes and guardrails. And so on.

Currently, people are the best at synthesizing this information based on access to people, often non-contextual resources, internal content you might not want to share with a commercial LLM vendor, and plain old experience.

I’m sure somewhere in the world there is a product team that writes extensive, detailed, accurate user stories and acceptance tests covering all expected use cases. Its code is clean, clear, well-documented, and accompanied by a comprehensive suite of tests. Those test suites use real-world data (including the error cases). The interface is uniquely intuitive to both people and computer use models. The customer use cases are clear, finite… and already documented.

Sure, an appropriately trained LLM could be fed that information and generate some documentation.

But the best person to feed the LLM and make sure the output is usable is an experienced technical writer.

For a novel product, it takes people to build the corpus of contextual information that an LLM would need to generate documentation, training, or marketing content.

Once you’ve built that corpus of knowledge, sure, you could feed it to an LLM to run a chatbot or draft more documentation. But it starts with experienced technical writers and those same technical writers — with deep knowledge of the product and its customers — are the best people to steer that process.

Technical writers have the skills and experience to know what to ask the LLM to produce and to confirm that it generates useful and accurate documentation. Technical writers coordinate between internal experts, sales, support, engineers, and users, making sure the right knowledge goes into the LLM and the right artifacts come out.

The job is likely to change but is perhaps more critical today than ever.

Technical writers have never been a high priority at most companies. Even less so at early-stage tech startups, which are the most likely early adopters of AI-based “help.” Executives at companies of all sizes are going to be sorely tempted by the thought of replacing writers with tools.

It would be a false economy.

An LLM needs a broad context of relevant information from which it can generate an accurate, useful response. An LLM is of very limited use if it knows nothing about your new product.

An experienced technical writer builds that broad context and then works with the LLM to expand it further.

I work mostly in developer tools and data science. For the last two years, I have extensively used LLMs, which have become a critical part of my documentation toolkit. I am all in on the capabilities these tools offer. They are a force multiplier for writers, particularly at tech companies.

But it’s not the tool that makes useful documentation. It’s my 30+ years of experience knowing what needs to be documented, how it should be documented, and getting the tool to help me create that documentation more quickly, more extensively, and more accurately.

I also love how quickly I can write my own custom tooling now.

There’s still a lot of controversy about whether Deckard is a replicant in the movie Blade Runner. You can interpret the film as you like — and I have my own strong feelings about it — but I think costume design conveys a lot about what the original production team thought about the characters.

For this post, I won’t be getting into the history of “Deckard is a replicant” except to say that’s never been my interpretation of any version of the film, and Deckard is not an android in the Philip K. Dick novel from which Blade Runner was adapted.

What I’d like to lay out here is some evidence from the Blade Runner production design that appears to clearly delineate who is human and who is replicant. Or, more specifically, to delineate the “human-ness” of a character within a given scene.

The evidence I want to lay out here indicates that costuming within the film signifies where a character exists on a spectrum of human-versus-replicant. Human characters have been given costumes rich with color and texture. Replicants are costumed in shades of black, white, and gray. It’s no more complex than that, and shifts in costuming seem intentionally used to indicate that the human-ness of some characters shifts along with certain points in the narrative.

Let’s get to some examples. We’ll move more or less along with the story since that approach best shows how some twists in the story are paralleled by changes in costuming.

We first meet Blade Runner Holden (in a beige or tan suit) giving the Voight-Kampff test to Leon (wearing all white).

Brown, earthy colors are quickly associated with cops here — humans who do dirty work.

Deckard (eating noodles) is wearing a brown overcoat, though with a maroon shirt peeking out. Bryant is wearing shades of beige and brown.

Gaff, like the others, wears a brown coat, but underneath: blue, pink, yellow/gold — intricate patterns, a rose on his lapel. Maybe the most vibrant palette of any character in the film. Is Gaff the most human, the most internally vibrant? He “knows” things, or intuits them, and leaves clues.

I suspect Gaff represents a chorus of sorts, commenting aside on what the actors on stage won’t say. (And coincidentally, Gaff is a man of few words, but words that say volumes when he does speak.)

At the Tyrell offices, we meet Rachel. Black suit. Black hair. Pale, white skin.

Rachel’s bright red lipstick is an interesting touch. Is it meant to be a face Rachel puts on to appear more human? The use of makeup has some parallel moments later in the film, the crowd at Taffey’s nightclub, Zhora, and Pris all wear makeup that could be interpreted as either hiding or accentuating their true identities.

Eldon Tyrell appears suddenly wearing sumptuous royal blue and white. I’ll get back to the connection between Tyrell and his bright white wardrobe later….

In this scene we get a closer look at Deckard’s clothing: a brown sportcoat and trousers, but check out that shirt! Blue. Burgundy. Yellow or perhaps gold. And an intricate pattern across his shirt and tie.

Abdul Ben Hassan, the snake merchant, wears a red, patterned tie and red fez against an immaculate white suit. (Again, we’ll come back to the white later.)

The first time we see J.F. Sebastian he’s wearing a highly textural gold, green, and red jacket. Pris, in contrast, wears all black except for her white hair. Even her bag, boots, and makeup are black.

The contrast is even more obvious later when we see cleaned-up Pris with Roy: black, gray, and white.

When Sebastian is with Roy and Pris (“We’ve got a lot in common”…) and reveals that his Methuselah Syndrome makes him unable to work off-world — less than fully human — he’s removed his colorful jacket and is now wearing a white, gray, and black striped sweater.

The scenes in which we see Taffey Lewis’s nightclub are short, but interesting to see the bustle and color of human social life. I don’t think we learn a lot from these scenes, but I do think the hair, hats, and makeup comment on the underlying humans-versus-androids thread:

• On the one hand, humans who have grown up with the freedom and experiences of a full life socialize in a colorful, vibrant, visually exciting environment. The costumes are amazing. Compare that to the quiet, childish, furtive social moments between the replicants.
• On the other hand, even the humans put on costumes, pretending and preening, perhaps trying to be someone at night much more interesting than during the day?

Within this vibrant scene: don’t be fooled by Zhora’s sparkles, she takes off her fake snake and silver sparkles, and changes into a (very scant) costume of black and clear!

Rachel on the run, shows up at Deckard’s apartment wearing a grayscale suit. Lips still red, but her makeup is coming off.

Deckard is having a tough day. We get a better look at his shirt of many colors, though.

What’s my point? In almost every scene, we see consistent costuming by which human characters are wearing colors and androids are wearing black, white, and gray.

• Leon (Tyrrell) – White
• Holden – Beige
• Deckard – Brown, Blue, Burgundy
• Gaff – Brown coat, but underneath: Blue, Pink, Yellow/Gold – Intricate patterns
• Bryant – Beige, Brown
• Tyrrell – Blue
• Rachael – Black
• Roy – Black, White
• Leon – Black
• Hannibal Chew – Brown, Gray, Yellow (Very muted colors in this scene)
• Rachael (Deckard’s Apt) – Black
• Pris – Black, Silver, Gray, White – Pink makeup (like Rachel’s lipstick?)
• Sebastian – Green, Red, Yellow
• Abdul Ben Hassan – Red, White
• Rachael (Phone) – White
• Taffey Lewis – Green, Blue, Red
• Zhora (Salome) – Silver
• Zhora – Black, Clear
• Deckard (Taffey’s Bar) – Burgundy, Red, Yellow, Seagreen, Blue – Firebird pattern!
• Rachael (Street) – White, Gray
• Rachael (Deckard’s Apt) – Grayscale
• Pris (Sebastian’s Apt) – Black, White
• Roy – Black, Gray
• Sebastian – White, Gray, Black (“We’ve got a lot in common”…)
• Sebastian (Tyrrell’s Room) – Brown, Red – Human again, appalled by Roy.

As I mentioned earlier, there’s one potential contradiction, which is the white costumes worn by Adbdul Ben Hassan early in the film and Tyrell later in film. I think this use of white makes a different point, which is that of the holy creator. Both Hassan and Tyrell are, in a sense, gods, bringing life to their creations.

Note that in Tyrell’s room, he references the prodigal son story from scripture, and the room is lit by candles, perhaps a reference to Prometheus or Icarus?

The white Tyrell costume in this scene also connects back to the first scene in which Leon appears to be wearing all white, and the white dove in Roy’s final scene.

From a production design point of view, Blade Runner appears to have been created with the intent to portray Deckard as human. Over various cuts, attempts were made, apparently, to muddy those waters, but for me they don’t hold up.

There’s a lot more to discuss about this film. Perhaps in a future post I’ll move on to what “human-ness” means in Blade Runner and how it plays with ideas common to some of my favorite Ridley Scott films: servitude, enslavement, and the inability to live fully under those circumstances.

Current release: mini-control-markers-0.4b.vmdx

There are two kinds of control indicator here:

• Axis and allied control indicator overlays
• Axis and allied control indicator counters

These do not replace the built-in VASL control markers, but provide additional, optional markers with a different appearance and some additional features.

Mostly, they look different: these mini control markers use smaller national icons with transparency.

The mini control overlays are a new idea. They stay in place and don’t get mixed up with counters. And they are kinda neat looking in a low key way.

Credit for the idea goes to Neal Ulen and Stew Stewart. I saw Neal using something similar to this in one of his ASL Bootcamp videos and asked where he got the cool control markers. Neal’s response was “The small ones are a modification done by Stew. But if you update to a new VASL version they get lost…”. So I set out create my own extension version.

Much appreciation to Neal for his time testing and giving feedback on early versions of this extension.

Between the axis and allied versions, they currently support the following individual nation icons:

Allied: Russia (PRoC, DPRK), US, Britain, France, Free French, Poland, Nationalist China (RoC), RoK.

Axis: Germany, Finland, Italy, France, Japan, RoC.

The counters are for folks who want the traditional control counter experience, but with transparent counters. The counters are stackable for control that is specific to, for example, building levels.

The control counters also show up correctly for the hover popover for a hex.

Both the mini markers and mini overlays support Ctrl-F “Flip” to switch between axis and allied markers/overlays. When you flip, it logs a control change message with the affected hex to the chat.

You’ll find the overlays in Draggable Overlays > Map Annotations > Mini Control Indicators. There’s an Allied mini control overlay and an Axis mini control overlay.

They support the following commands:

• Shift-select – Select overlay
• Ctrl-[ and Ctrl-] – Toggle nation icons
• Ctrl-F – “Flip” between Axis and Allied control

You’ll find the counters in VASL Counters > Other > Map > Mini Control Markers. There’s an Allied control counter with transparency and Axis control counter with transparency.

They support the same commands as the default VASL control counters, including:

• Ctrl-[ and Ctrl-] – Toggle nation icons
• Ctrl-F – “Flip” between Axis and Allied control

Which is no easy feat. I’m still working on it months later.

After a few games and still having fun with it, I thought it might be worth offering my suggestions to the eternal question: “how do you learn to play ASL?”

I chose to dive straight into the full system rather than the ASL Starter Kit (ASLSK), but the starter kits may be exactly the right thing for you. Either way, my suggested resources will be relevant.

While my friend and I chose to go full ASL rules, we are flattening the learning curve by starting with just the infantry rules and playing just infantry scenarios. Later, as we gain confidence, we’ll add ordnance and perhaps armor.

With that explanation out of the way, let’s get to some of the learning and play aids I’ve found useful so far.

First, you’re going to need some rules. I recommend the Electronic Advanced Squad Leader Rulebook (eASLRB). It’s the full rules with all the latest errata incorporated in a searchable, indexed PDF. Rules references in the text link directly to the referenced rule. You can full-text search. As a new, learning player I’m constantly referencing the eASLRB and being able to quickly find the relevant term or rule has been extremely helpful.

Neal Ulen’s Advanced Squad Leader Academy Boot Camp – Advanced Squad Leader Tutorials on YouTube are an incredible resource for new players. I cannot overstate how critical these were to helping me wrap my head around the rules.

My suggestion for new new players is to read ASLRB chapters A and B without getting too caught up in the details. Just get the words in your head. Watch Neal’s Boot Camp tutorials. Then go back and read chapter A more closely. Having seen the tutorials, the rules will make more sense.

The Texas ASL website has some great play aids under “Downloads”, starting with the indispensable ASL Rules Summary by J. Yuzwalk. The turn phase breakdown here is something I refer to constantly.

You may also find Jay Richardson’s Phase Quick Reference handy.

Jay’s ASLSK Tutorials are must-read resources for the new player. Jay really unlocked defensive fire in the movement phase for me.

From there I’d say start playing. I’ve alternated playing with my friend and playing solo games, referring back to the rules and play aids as necessary. I own several of the initial ASL modules including Beyond Valor module, but I mostly play on the computer using the Vassal hex game engine and VASL module for ASL. Neal has a terrific playlist of VASL 101 – Virtual Advanced Squad Leader Tutorials to help you get started.

You’ll need some scenarios to play. I found the Advanced Squad Leader (ASL) Beginner Scenario List on the Itinerant Hobbyist blog, who credits the list from a poster on Boardgame Geek, via Gamesquad. I’ve seen this list on other sites as well. The beginner and infantry-only scenarios are a good place to start.

I hope this gets you on the way to playing Advanced Squad Leader. Have fun. Roll low.

I’m fortunate to live in a state that has been relatively less impacted by Covid-19 than many other places. Still, we’ve followed protocols to keep ourselves and our community safe, while trying to keep tabs on the progress of the pandemic.

Vermont has done a good job providing public access to a variety of daily Covid-19 statistics through the Vermont Open Geodata Portal, including:

VT COVID-19 Daily Counts VT COVID-19 Hospitalizations by Date VT COVID-19 Cases by County Time Series

There are a few others, but these provide the most useful time series data, updated daily, with the latest data available in GeoJSON format via API.

That said, I was less thrilled by the Vermont Department of Health Covid-19 Dashboard, which focuses too heavily on daily counts and overall totals.

Daily counts are hard to intuit into trends. 2, 5, 8, 3 sounds like not a lot. But those numbers add up. What I wanted to see was trends — how those small numbers added up over time.

I also knew that those two new cases stayed sick — or at least contagious — for some time after a positive test, and those “estimated current cases” add up.

Knowing the data was available via API in JSON format, I chose to parse the data and create my own chart. I had recently edited Glenn Prince’s Data Cleaning with Python and Pandas article series, which inspired me to try out Jupyter Notebooks and Pandas for this project. The built-in Matplotlib charting functions were fine for my use so I did not explore any specialized charting libraries.

I highly recommend Glenn’s tutorials for an introduction to Jupyter and Pandas Dataframes. It’s very intuitive and easy to manipulate data once you wrap your head around these tools.

Charting turned out to be slightly more complicated — mostly because I insisted on employing a few edge-case configuration options that were not well documented. I made notes about these options in my notebooks.

There are two notebooks:

• VT-Covid-19-ByCounty.ipynb – county-by-county test and hospitalization data
• VT-Covid-19-Data-Pandas.ipynb – full-state data including tests, hospitalizations, and deaths

The source is available in a repository at vt-covid-jupyter-charts if you want to experiment.

Head over to HTTP Archive and check out their trends graphs. Notice anything? That’s right, web pages keep getting bigger and more complicated. The problem here is that — particularly in e-commerce — consumers of your site expect it to load and become interactive quickly.

Turns out, the problems involved and solutions needed to fix them depend, mostly, on straightforward, Web Dev 101-level knowledge and technology. I recently wrote a short e-book on the subject for O’Reilly, Web Page Size, Speed, and Performance (free, registration required).

There’s also an accompanying blog post on O’Reilly Radar, It’s time for a web page diet.

Slimming down web sites is not necessarily a matter of learning new and sophisticated programming techniques. Rather, getting back to basics and focusing on correct implementation of web development essentials — HTML, CSS and JavaScript — may be all it takes to make sure your own web sites are slim, speedy and responsive.

Interesting side note: mobile web users (and probably app users as well) expect faster interaction than on the desktop and are more likely to ditch an action if it’s slow. Think about the implications of that complication on your app development plans.

OK. Functions are a pretty big concept for a new programmer to grasp.

I also made a major mistake: too much talking, not enough coding. The kids are much happier and seem to understand better when actually writing code, making things happen and experimenting on their own.

I did experiment with a different kind of example, however, and it seemed to bring some fun and understanding: “human functions.”

Basically, the kids became functions and we interactively ran the program by talking to each other. Here’s how it worked.

First, I took one of the students, Sophie, aside and gave her some secret instructions:

Take the word you’re given and use it in a sentence.

Then, one of the other students would “call” her with a word: “Sophie: donuts.” Sophie would respond “I love to eat donuts.”

We had some fun with it, as 10 year old kids will, and changed up the examples a bit. As I explained, this pretty much equates to the following code.

def sophie(word)
    puts "I love to eat " + word
end

sophie("donuts")

This seemed to help the kids understand a lot better. I think next class we’ll start out with more exercises like this before moving to the code. We could get multiple human functions involved to demonstrate how functions generalize tasks within a program.

For example, here’s a simplified version of our storytelling program.

def prompt(choice1, choice2)
    print "Which do you choose (%s or %s): " % [choice_1, choice_2]
    answer = gets.chomp
    return answer
end

def story
    puts "A zombie appears. Do you run or fight?"
    action = prompt("run", "fight")

    if action == "run"
        puts "Chicken! Bawk bawk bawk!"
    elsif action == "fight"
        winorlose
    end
end

def winorlose
    puts "Rolling the dice..."
    diceroll = 1 + rand(6)

    if diceroll > 3
        puts "Yay! You win!"
    else
        puts "Sorry, you lose."
    end
end

My human functions can run this program.

1. Kendall starts the story, and passes the the prompt to Arden.
2. Arden asks Teddy the question and returns his answer to Kendall.
3. Kendall either ends the story (“run”) or calls Sophie (“fight”).
4. Sophie rolls a die and, depending on the roll, tells Teddy whether he won or lost.

We’ll have to see how it works. Looks like I’ve got a bit of writing and scheming to do before the next lesson.

Last year my older daughter started fifth grade and brought home a school-supplied MacBook. Which is great. I think it’s important to give kids a chance at an early head start to develop technology and programming skills — an early taste, anyway, to see if they like it — particularly the girls.

I set about looking for an appropriate learning resource to teach my daughter. There’s a lot out there. Unfortunately, none of it quite appealed to my preferences.

I wanted something easy for me to read, parse out what was being taught, and know what to pass on to students. Many of the course materials I reviewed required a lot of up-front reading, then I’d have to create my own teaching notes.

Adults and older children might be motivated to learn programming for its own sake, but I think younger kids (8-13 at least) don’t have the same motivation (exceptions discussed below).

Learning while doing something fun, however, seems to work. So I wanted to start with an interesting goal and make sure each step along the way was both educational and fun.

Finally, the laptops at my daughter’s school are locked down, so I needed something that required no software not already installed on the machines.

Ultimately, it seemed easier to create my own materials. As a bonus, as mentioned in my posts about writing about code, I’d probably learn a lot in the process. And I did.

RubyStory

The result is a course I wrote called RubyStory and you can grab all of the materials from Github. The details are covered in the readme.

The course materials are intended for teaching to kids. I suppose they could be used for self-instruction, but my assumption is that kids who are ready and motivated to learn programming on their own are probably also ready and motivated enough to learn from a book or a more traditional tutorial.

I recommend Zed Shaw’s Learn Python The Hard Way and Rob Sobers’ Learn Ruby The Hard Way. Both influenced the storytelling aspect of RubyStory.

The RubyStory materials are intentionally sparse. There’s an outline and sample code and handouts. There’s a slide deck, but it’s mostly just to show the code examples, which students can then type on their own.

The outline provides a concise overview of the topics to teach, but be prepared to fill in details, answer questions and riff a bit as your students require.

I wrote this course with the assumption that the teacher already has some basic programming knowledge. You don’t need much:

• Creating and using variables
• Strings and integers
• Basic math and Boolean logic
• Printing messages to the terminal
• Capturing input from the command line
• If statements
• Functions

That’s all we use. Even if you know nothing about Ruby, you should be able to pick it up quickly. (I knew almost nothing about Ruby before starting this project.)

Why Ruby?

As you can tell from the minimal set of programming concepts covered by RubyStory, it’s hardly language specific nor does it really “teach Ruby.” In this case, Ruby is a convenient tool.

First, Ruby is already installed on every recent MacBook. The version installed is not important.

We don’t need any special tools to program with Ruby, just Terminal and a text editor. TextEdit isn’t the tool I’d prefer — syntax coloring would be a nice feature — but we can live with it for simplicity. (The slides do include syntax highlighting.)

Ruby has very simple syntax and very little necessary punctuation. Whitespace and semicolons aren’t that important and there are very few parentheses and brackets to worry about. I’ve found that kids have enough trouble with accurate typing. Simple syntax makes troubleshooting much easier.

Plus, I wanted to learn some Ruby. And I did.

Next Steps

Please fork the RubyStory repo and give teaching a try. I am continually updating the materials as I teach and learn from the kids — what the enjoy, what they build, what questions they ask, where I can help them go next. Let me know what you learn while teaching with RubyStory.

As written, RubyStory should be easily adapted to Linux systems, but I haven’t yet into what additional material would be needed for Chromebooks or Windows. It’s on my to do list.

Other than that, I’m now focused on using RubyStory for teaching in my community. I hope you will, too.