Enable Learning in Technical Writing

My goal writing documentation is to enable a student to learn, give them confidence they can learn, and not just copy-paste their way.

This is not easy and I'm still learning myself what is the best way to organize any given set. This post covers my thinking around, it is a deeper follow on to previous notes on technical writing.

Muad’Dib learned rapidly because his first training was in how to learn. And the first lesson of all was the basic trust that he could learn. It is shocking to find how many people do not believe they can learn, and how many more believe learning to be difficult.

The Humanity of Muad'Dib by the Princess Irulan [^1]

Overview

For documentation you can create a tutorial that walks a student through a serious of steps and — assuming they have a close enough setup to yours — it will all work as expected. However, did they learn something? Beyond, if I copy and paste these commands from that site it works.

What happens when the student has a different setup? Maybe they tried the tutorial 6 months ago, gave up and are coming back again but now with the detritus of their failed attempt. Maybe they are using an outdated version or you haven't updated your tutorial with the newer version.

These are a few of the countless differences that lead to students getting frustrated, giving up, walking away, and telling themselves it is too hard, this is not for me. The student will stop trying to understand and rely on copy-paste, if I just use Google enough I can find the right code.

Narrative Construction

How to create your documentation to help students?

Jerome Bruner studied human cognitive psychology and developed a learning theory of narrative construction. This is that students create a narrative that constructs their view of a concept, as new ideas come in they add and modify their view to fit the ideas.

The goal of your documentation then is to provide new information that can be used to expand (and/or correct) their view of the fundamental structure of the subject.

For example in WordPress when I'm documenting a feature for the new editor it may require reinforcing a proper understanding of how plugins work, since new features are added using plugins.

"The teaching and learning of structure, rather than simply the mastery of facts and techniques is at the center of the classic problem of (knowledge) transfer" [^2]

The explaining and understanding of the fundamental structure is critical to learning a subject. However, this does not require over explaining or confusing the student. You don't need to dive so deep into the fundamentals that for example saving a file you end up covering the magnetic properties of hard drives.

An example adapted from Bruner's Process of Education:

To learn algebra, solving an equation with unknowns, say 3x + 7: 16, a student must grasp the ideas of commutation and association. It is not important a student knows the formal name and definitions of these mathematical properties — I have a degree in mathematics and still had to look the names for this post. What is important is the learning the underlying structure and rules on how to use them, it is often unconscious.

Likewise for writing, a student must have an understanding of the rules of English and sentence structure, but formal names are not needed to know these two sentences express the same action: "The ball was thrown by the boy." and "The boy threw the ball."

"Giving students an understanding of the fundamental structure of whatever subjects we choose to teach. This is a minimum requirement for using knowledge, for bringing it to bear on problems and events one encounters outside a classroom." [^3]

This understanding of structure and developing an intuition on what can be done and how things work is critical to actually learning and being able to solve some of the issues outlined at the beginning.

Techniques to Encourage Learning

As I said above, this is by no means an easy task and depending on subject, student, and instructor there is plenty of variance of working techniques and implementation. Here are a few suggestions:

1. Learning is an active process
2. Encourage action through dialog
3. Use mixed media
4. Include exercises
5. Self Discovery
6. Spiral Organization
7. Troubleshooting

Learning is an active process

Learning is an active process, the student must engage with the work and actively do something, be it typing, working out problems on their own, or whatever, there needs to be some sort of engagement.

As a writer of documentation, you can not solely rely on the student's motivation and desire to learn. You need to create your documentation and systems in a way to encourage engagement.

A great example of this is A Tour of Go that presents a split screen of instruction on the left and an active working playground to write and test code. 👌

Active Dialog

In your writing engage in an active dialog, invite the students to act. You can include phrases like "Please try", "See what happens", "Explore yourself". The goal here is to empower the student to have confidence to try and explore, so they can apply the concepts they are learning immediately.

If you can, create your tutorial in a way that encourages creating and destroying a dummy project. If a student knows that they can mess things up, but then recover it will encourage experimentation.

A good example of this is the React practical tutorial; it includes a pre-built environment using CodePen, one click to have a new setup.

Use Mixed Media

People have different learning styles, so it is important to vary your forms of media to communicate the subject matter. For example, don't just rely on text to describe, you can include a diagram to illustrate a system or workflow.

Also, don't feel bad about repeating yourself, if you publish something in a video and also include text, you don't know what will connect with people and help them grasp the ideas and concepts.

An example: I noticed this when documenting a git workflow about pull requests, there are several steps involving different repositories and machines. My text description explained it well, but including this diagram can help someone visualize where and how the steps flow.

Example Use of Diagram

Self Discovery

A technique you see in a classroom but rarely in documentation is the withholding of information and requiring the student to discover the answer on their own, applying what they learn.

This technique works much better for tutorials then reference documentation, you don't want to be withhold info from your API to let the developer "figure it out".

This goes back to the concept in my technical writing notes that there are different types of documentation and you need to cater your writing and techniques to these different audiences.

You can do both, ask a question to engage the student but hide the answer and let them think then reveal. Using the details and summary HTML tags allows you to add this small part of interactivity.

What tag can you use to hide and reveal information?

Is this too meta? See the MDN docs for details tag usage.

Exercises

You can include exercises for the students to do. Just like in a school math book, explain the concepts, show an example, and then give an exercise for the student to complete demonstrating their knowledge of the concept.

An excerpt from one of my favorite documentation, the IBM Displaywriter Operating manual at the end of each topic they include an ON YOUR OWN section:

ON YOUR OWN

You can use these techniques to insert and then delete underlined and centered material. Experiment with deletion. When you are finished, END the Smith Letter document, and then print it out

Spiral Organization

Organize your documentation in a spiral structure that continually builds upon previous knowledge. Students learn by constructing their view of the system, your documentation needs to slowly help them build a correct view.

Creating good spiral documentation requires careful consideration of the students and trying create documents for people at various skill levels. You want to aim for the lowest levels to the point of almost over-explaining, because more experienced developers can skim to the points that interest.

Your document does not need to cover everything, use links generously. By linking to lower-level concepts or additional details, you allow those who are interested or need that information to explore without muddling the goal of your document.

Also, specify your assumptions up front. If the tutorial is intended for experienced developers without knowledge of your framework; or is it intended for beginners. This requires you thinking about what you assume when writing the documents.

A good example of specifying assumptions is React documentation again. They have a section titled "Knowledge Level Assumptions" and even include links to help.

Troubleshooting

Allow for mistakes. As mentioned in the active dialog section above, give instructions on how does a student start over or recover from mistakes.

As you are creating your documentation, keep track of all the little things you did wrong, all the error messages you see, anything that trips you up. Include all these mistakes in a "Troubleshooting" section.

What might they see if they run something wrong? What if they make a change and nothing happens? An error popped up, what does it mean, what to do?

This requires creating your documentation with thoughtfulness on everything you write. For example, if you are creating a doc for beginner JavaScript and you mention an error will show in the console log, you need to link to or explain where is the console log and how to show it.

If you are writing a doc for advanced JavaScript you probably can assume they know about the console log. The challenge often tends to be, how do you know if the student is a beginner or advanced.

Summary

The goal of your documentation is to enable people to learn your system. Use various techniques to build the student's view of the structure for greater understanding. When creating your documentation use various techniques to reach and engage students. Encourage active participation using exercises, self-discovery, and different media. Organize documentation to build upon itself, start with smaller concepts and build up. Finally, allow for mistakes, they happen, it is fine. Acknowledge this and give the student techniques for recovery.

[^1]: Dune, Frank Herbert, 1965

[^2]: Bruner, Jerome. The Process of Education, Page 12, 1977 edition

[^3]: Bruner, Jerome. The Process of Education, Page 11, 1977 edition