Made by
Made by
Dictionary
Erin McKean, founder of the newly-not-for-profit Wordnik.com, the world’s biggest online dictionary, knows quite a bit about unpacking expansive ideas and making them simple and clear. And, as a “community-taught” Javascript developer, she’s blazed through more than her share of tutorials and demos.
It was this experience of collaborative learning through the community that inspired Erin’s session at the upcoming DevRelCon London 2017, ‘Making the implicit explicit: modelling developer norms and tools’.
Erin rebuts the term “self-taught” in regards to her programming abilities because, thanks to the wealth of resources available for developers online, she affirms, “I did not learn all by myself!” However, for someone new to programming, Erin found that many tutorials tend to neglect to mention best practice in favour of perceived simplicity.
Many developers have a tendency to strip away details they deem “irrelevant” to their audience. Things like production norms that, to their experienced eye, go without saying. The problem is that, for new learners, being told that code ‘isn’t suitable for production’ doesn’t help them learn what makes code suitable for production.
Ideally, she believes, tutorials should be pitched on the assumption that “today’s learner is going to be tomorrow’s deployer.” Or, equally likely, that what is learned in the morning might be deployed by the afternoon.
But, it’s not just a matter of assumed knowledge. Whilst some developers might favour brevity, there’s also the fact that cutting the scope of an explanation down often means a tutorial is much faster to finish. And, a lot of the time, “Done is better than perfect.”
When writing tutorials, Erin advises beginning by asking, “What do I have to know for this to make sense?” And, don’t be afraid to be ridiculous. “You can always cut over-explanations, but your user can’t supply missing ones.” For example, ‘I have to understand that the world is round’ might actually be useful for explaining time zones!”
Bloggers who are good at seeding their pieces across social media are usually experts on the preferences of their community. However, whilst a Batman-centric analogy might fly perfectly with one niche set of developers, it won’t make sense everywhere. It’s also why lexicographers don’t tend to throw analogies into explanations the way that a developer advocate might be inclined to do.
Erin is emphatic that, to be useful, an analogy must be both familiar and representative. For example, whilst, “choosing the right cloud hosting provider is like going on a cruise’ might be familiar,” it’s not what she would consider representative. As she notes, “People like analogies, and a good analogy is worth a thousand words of dry explanation…Presenting an analogy that compares some coding principle to an obscure physics concept might be representative, but it would not be familiar to a wide audience.”
There’s also the fact that many an analogy rests on the shoulders of a hackneyed old stereotype. Erin adds; “It should go without saying that a good analogy should also be inoffensive. We’ve all seen developers get in trouble when they try to make analogies that compare code to dating or use other metaphors that reinforce, rather than challenge them.”
Language can be a powerful tool in shaping the culture and inclusiveness of a community. So, “if everyone in your audience has to be just like you for your analogy to work, it’s probably not going to be effective.” Which is why, although she’s a prolific seamstress, you probably won’t hear her make any throwaway references to fabric selection the next time she’s doing a live demo. Unless maybe it was somehow tied back to Ada Lovelace and her looms. [Organiser’s note: this actually would be brilliant. Erin, how about you talk about that at the next DevRelCon?]
Erin’s lexicographic background means that she’s hugely diverse in her reading, and to this day, she still enjoys dipping into obscure media like Tube and Pipe News – even if it’s unlikely she’ll be called upon to use that knowledge. She has a similar enthusiasm for relatively obscure tutorials, likening them to interesting recipes.
“There are some recipes you see that are for reading, not eating: they require immense time and energy or very expensive ingredients or are for dishes you simply don’t want to eat. And some tutorials are also read-only (especially ones that seem to be directed at highlighting one obscure feature of a vendor’s product).”
To Erin, a good tutorial (or dish) balances the time it takes to make with the result you achieve: “I’m willing to put more effort into making a fancy cake than I am into making a sandwich, for instance. A good recipe doesn’t require outlandish ingredients (an obscure library, an expensive paid service, or a lot of computing resources).” Moreover, like a favourite stir fry, it should also allow room for experimentation and expansion.
Dictionary editors read as many example sentences as possible before writing definitions, in order to make sure that they have a full picture of how a word is used. Erin takes a similar approach with technology, ensuring she reads around a topic exhaustively before attempting to explain it to somebody else. For her, there are commonalities between writing definitions and explaining code. Both, she says, require that you follow a maxim often attributed to Einstein: “Everything should be made as simple as possible, but not simpler.”
However, she warns against a totally binary approach. Whilst some problems might be stretching, “if you make them artificially simple, you do the reader or the learner a real disservice.”
A lot of this comes down to the information that’s included in a tutorial or example. “What is necessary is what is required for your code to work: but that may not be sufficient for your example to be understood. You have to include enough context and supporting material so that the learner can actually make use of what you’re trying to explain.”
Understanding this tension between what is necessary and what is sufficient can make for a tutorial that goes beyond merely elucidating a singular concept. In fact, to quote Erin, it might just chain together a few related technologies in a way that “illuminates an entire ecosystem” for someone.
Get your tickets to see Erin’s talk about many others covering the latest thinking in developer relations, developer marketing and developer experience at DevRelCon London 2017 on December 6th.