A Learning Manifesto

I’ve been thinking alot about how people learn, how I learn stuff. I wonder why so much learning material is no good, and what makes for good learning material. I’ve seen such bad content that it’s gotten me mad, and I decided to write a manifesto.


What’s the problem?

Too much learning material does not meet the needs of learners, or worse, confuses them, annoys them, frustrates them, misleads them.

  • Learning material that provides too much, or more often, no background material to explain not just which buttons to press but why.
  • Learning material that assumes too much knowledge.
  • Learning material that is difficult to navigate.
  • Learning material that I can’t try it out myself.
  • Learning material that is made of recycled parts that don’t fit together.
  • Learning material that is too easy or too hard.
  • Learning material that doesn’t provide a path to growth.
  • Learning material that doesn’t understand where the learner is coming from, whether their role, their level, their language, their work environment.
  • Learning material that plain doesn’t work.

Especially on the last point: I am amazed at how much learning material is not checked against the product, not tested at least 3-4 times before release and regularly after release. At the very least, the learning material should be accurate.

What makes good learning?

You have to ask: how do people learn? I mean in life, generally, or when we look at kids. What is needed:

  • Empathy – This means we need to be thoughtful of the user, making them at ease and providing what they need when they need it. Among the requirements:
    • Don’t assume knowledge they may not have
    • Ease learners through the topic with “learning journeys”
    • Anticipate the questions they would ask and then answer them, even if the questions don’t need to be answered right then
    • Don’t force them into dense documentation to get knowledge to complete a tutorial
    • Give them all the information they need for completing the tutorial
    • Provide learning at different levels and for different personas
    • Let people contact the creators.
    • Give positive feedback from time to time
  • Practice – Learners need to practice … and practice and practice. Make sure they have systems to practice on, and plenty of tutorials.
  • Allow for Mistakes – People learn by making mistakes, and you need to allow them make plenty of them. (Later, I’ll tell you how I will never forget the difference between accuracy and precision because of a mistake.)
    • Corollary: Give people time to play around with the product, to go off the tutorial script, to press the buttons, to do the tutorial over and over again, to experiment on their own.
  • Build Community – Community isn’t a prerequisite for learning (many people learn on their own), but it helps provide some of the things that are required.
    • Enable small “study groups” where people help each other.
    • Allow people to ask questions – and make sure there are people to answer them.
    • Let people help others … no better way to know if you know something then to have to teach it to others. And people also learn by trying to solve other people’s problems, and they also learn about how the product can be used or features of the products from these questions.

There are 2 key requirements needed for providing the above:

  • Resources – You must devote resources, or reallocate resources, so content creators can learn the topic, can create the material, can test the material … and test and test, and work with the community of people using their material. I think some existing resources can be reallocated (like documentation), but more on that later.
  • Experts – You must have people who know the product and the user base to create the material and talk with the community. Yes, they can be engineers who learn to write or writers who learn to engineer. But either way, they must be immersed in the product, and be excited about it.

My Background

I tend to be a tinkerer, less a builder. I would take apart my Mattel Electronics Handheld Football game, all the rage when I was in high school. I wanted to know how it worked (I was less good putting it back together).

I am also a writer, or have been. I found my way by working for the school newspaper as a writer, but also as a photographer, a city editor, a paste-up guy, and an ad salesman. I worked at the Cape Cod Times and The Baltimore Sun. AFter getting a master’s in computer science, I became an API technical writer at SAP.

I wrote lots of documentation for the SAP Netweaver Enterprise Portal, SAP Web IDE, the short-lived River Development Language, SAP Business One, and even one of the products for Large Enterprise On-Demand. About 5 years ago I went to manage the Developer Relations tutorial system, both its technical side but also its editorial side – trying to set some standards, creating a template, encouraging everyone to test their tutorials and to update them, creating and managing the feedback channels.

The upshot: I’ve seen a lot of learning material, and a lot of it is bad.

The problem

Companies have to teach people stuff and the material to do that is no good.

Well, that description of the problem exposes a more fundamental problem: Why are we doing what we are doing, and do we have to do it at all? Said another way: Who are we talking to and what do they need?

If we look at a lot of the material out there, it really is pretty poor. We have gotten away with it because:

  • Many of our “customers” are developers who are willing or have gotten used to bad documentation and learning materials. See Crossing the Chasm for more on this.
  • In the past, many companies had money to send people to in-class training, which makes up for poor training materials, but at a pretty high cost.
  • Our industry is quite fluid, and products come and go and we can justify not creating good materials because the product likely won’t be around for long. (Let’s skip the idea that maybe bad learning materials contributed to the lack of adoption.)

What others have written

One of the sources that inspired me was the Cluetrain Manifesto. Written in 1999 – before the iPhone, before social media (in its current form) – the manifesto focused on how companies related to their customers. It complained that the relationship was one-sided, and the conversations one-directional. The hope was that the internet would enable more genuine conversation and relationship.

Most corporations, on the other hand, only know how to talk in the soothing, humorless monotone of the mission statement, marketing brochure, and your-call-is-important-to-us busy signal. Same old tone, same old lies. …

While many such people already work for companies today, most companies ignore their ability to deliver genuine knowledge, opting instead to crank out sterile happytalk that insults the intelligence of markets literally too smart to buy it.

While the above relates to the company-customer relationship, generally around sales or service, the same could be said around delivering learning materials and around the relationship between company and developers and all its learners.

Another inspiration was the early Sun Microsystems Java tutorials – “trails” I think they were called (here’s part of a preserved version). The first thing I remember is the navigation, and how every page seemed to be able to take you back and forth and I could always get back to the start of the trail. In fact, the navigation in Javadocs I always thought was the greatest thing, everything hyperlinked to its definition!

But also the documentation had a series of trails – long before SalesForce – at different levels, and definitely for newbies.

I have also been inspired by some of the lectures by Michael Wesch, who was when I first watched an anthropology professor at Kansas State University. I especially liked the lecture he did on how YouTube was changing people’s perspectives and the way they saw what was important and they they communicated (this was in 2009). His point was that people were looking for authenticity, and if you provide it people will respond.

There have also been many people involved in documentation/tutorials that have written about the need to engage people, whether in the content itself or via social media (or directly with the users). Tom Johnson is prolific with his I’d Rather Be Writing blog.

And I especially liked another blog, the name of which I can no longer find, which discussed when to create and not to create how-to videos, and within how-to videos how to teach things to people. The classic design was to show some slides to people, teach them stuff, and then to test them. But this instructor suggested that it better to “test” them first, for example, showing the problem or even asking them what their problem was, and then asking them how they would solve it. Only then would you provide some of the answers, relating them to what the participants had previously talked about.

The solution

DISCLAIMER: I will be oversimplifying the solution, disregarding issues of expense and resources and time, and complexities of multiple languages, time zones, and products. In my defense, there is not enough room for all of those issues, and besides, there are others whose job it is to implement things and take care of such issues.