Email courses for developers teaching something technical

Email is a bad place to put code, and this is what breaks

Mail clients wrap long lines, and a wrapped line pasted into a terminal is a syntax error the reader will blame on you. Keep every line of code under about seventy characters, or put it in the repository and link it. There is no third option that survives contact with a phone screen.

Several clients rewrite what you typed. Straight quotes become typographic ones, two hyphens become a dash, and the result is code that looks correct in the message and fails when it is pasted. Compose the course as plain text, turn off the substitutions in whatever writes it, and paste one of your own sent emails into a shell before the sequence goes to anybody.

There is no syntax highlighting, so the structure has to come out of the writing. Short blocks, one idea each, with the explanation before the code rather than after it. And never ask a reader to assemble fragments from three different emails: each day is complete, and the repository carries the state after each day as its own branch.

What the five days should teach

Teach one thing that runs end to end on the reader's own machine by Friday. Not a survey of a technology and not five loosely related tips. A small working system, built in five increments, each of which leaves behind something that starts.

Pin the versions in the first email and state the prerequisites honestly. Naming the database version, the language version, the twenty minutes a day and the fact that a local server is needed is information the reader uses to decide whether this is the right Monday. A course that reveals a dependency on day three has already lost the people who did not have it.

Day one has to run. The highest-value decision in a technical course is ending the first email with something on the screen in under ten minutes, because a reader who has run one command that worked has a reason to open Tuesday, and a reader who spent Monday on installation has a reason to stop.

Day four is what breaks on other people's machines. Every technical subject has two or three of these and you already know yours from the questions you answer. Naming them before the reader meets them turns the most common abandonment point into the email that gets bookmarked.

The objection your readers arrive with

It will be out of date. Your reader has followed a tutorial written eighteen months ago, hit a renamed flag on step three, and spent an hour discovering that the library moved. They now check the date before they read anything, and a course with no date on it is assumed to be old.

Answer that with versions and a date, both visible, in the emails and in the repository. Then actually re-run the thing when something major moves, which is a real maintenance commitment and the reason a technical course should be narrow enough to re-run in an afternoon.

The second objection is the register. This audience detects marketing language faster than any other and reads it as evidence that the content is thin. No exclamation marks, no claims about their career, no adjectives doing work that a measurement should do. Write it the way you would write an internal document for a colleague you respect.

What your sign-up page has to say

Put the specification on the page: the versions, the prerequisites, the minutes per day, the repository link, and what is running by Friday. A technical reader evaluates a course the way they evaluate a library, by reading what it claims to do, and a page of enthusiasm with no version numbers reads as a page with nothing behind it.

Link the repository before anybody signs up. It feels like giving the course away and it is not: the code without five days of reasoning is a repository like any other, and readers who clone it and never subscribe were never going to subscribe. What it buys is the thing that establishes credibility with this audience, which is being checkable.

Say a confirmation link comes first and that day one follows the click. Mention that mail containing code and repository links is filtered harshly, and ask the reader to look in the spam folder for the confirmation. It is the least surprising sentence on the page to this audience and it recovers real sign-ups.

The lines a technical sign-up page has to carry:

• What is running on the reader's own machine by Friday, described as a system rather than as a skill.
• The exact versions the course was written against, and the date it was last run against them.
• The prerequisites, including anything that has to be installed before Monday morning.
• Minutes per day, honestly, for somebody who has not seen this subject before.
• That a confirmation click starts the course, with a request to check the spam folder for it.
• A link to the repository, available before signing up rather than after.
• What day six asks for, which is a failure report rather than a purchase.

What the day-six email asks for

Ask what failed. One reply, with the step, the error and the versions, from every reader who hit something. It is a small ask, it is the kind of message this audience writes anyway, and it is the only mechanism that keeps a technical course true as the ground underneath it moves.

Treat the answers as a maintenance queue rather than as feedback. Three people reporting the same failure on the same platform is a bug in your course, and fixing it improves every future reader's Tuesday. No other audience's day-six ask compounds like that.

Put whatever you sell second, plainly, with the price and the scope. A book, a workshop, a hosted version, a support contract. This reader is not moved by urgency and is moved by an accurate description of what the paid thing contains, so write the description and leave the persuasion out of it.