Writing Beginner's Guides
Introduction
This essay was written by me, Brandon Nolet, in the context that I just finished editing a beginner’s guide I wrote yesterday, and I have some tips and tricks to dole out.
Verbosity
Being verbose is using or expressing in more words than are needed when describing a given subject, term, topic, or definition. See that? I was just being verbose with that first paragraph. And now I’m being explicit. Being explicit is when you are stating clearly and in detail, leaving no room for confusion or doubt.
These are two qualities your writing must have when writing a beginners guide. This is because you’re introducing something to a reader that they might not be familiar with. Verbosity is how verbose a given communication, in this case your writing, is. You would say that the level of verbosity in your writing must be high.
Defining words or topics, referencing documents or websites related to your topics, and explaining things in great detail are all things that are acceptable, and encouraged, in a beginner’s guide to any given topic.
With my Macros in org-mode guide, I wasn’t verbose enough the first time around and so some had trouble grokking the content in that guide. That’s not because they’re less intelligent or because they’re not able enough. That’s because I didn’t put enough detail in my explainations or made knowledge assumptions.
Knowledge Assumptions
The term knowledge assumption, at least to my knowledge, is not a term that is officially coined, so I’ll define it here. A knowledge assumption is when one, often unreasonably, assume that the reader, listener, or viewer is in possession of a given set of knowledge. Good beginner’s guides make very little assumptions about the knowledge set that someone has on a given topic and, optional but encouraged, include detailed references on topics that the consumer may be unfamiliar with.
By making few knowledge assumptions you’ll better be able to educate the reader, viewer, and/or listener on the topic you’re discussing. The reason for this is that you’ll be making the learning experience less tedious. By making the knowledge assumptions you’ll either be forcing the reader, viewer, and/or listener to perform extra research that otherwise would not have been necessary should you have took the extra seconds or minutes to write a detailed description on a given term.
Of course, there are limits to this. If you’re giving someone a tutorial on how to write an OS in [[https://en.wikipedia.org/wiki/C%5F(programming%5Flanguage)][C-lang], you’d reasonably be able to assume that someone has knowledge on what a computer is, or what an OS is. You’d also reasonably be able to assume that the person has familiarity with programming as writing an OS in any language is an extremely daunting task.
Examples Aren’t Always Enough
This is something that I struggled with when it came to teaching people. I’m someone who learns quickly by observing and then performing the task required of me. By performing the task, I solidify the knowledge that I need and, within reason, could be demanded to perform the task on my own, without needing to observe once more.
This is a position of quite high privilege. Not everyone’s minds are as malleable and not everyone can process this information as quickly. This is something that must be taken into account when writing a guide for someone who is a novice in your chosen point of discussion.
Step by step instructions can sometimes be a better way for people to learn. Sometimes someone has to memorize every single facet of a topic. Sometimes someone has to absolutely immerse themselves in a given topic, pulling sources left, right, and center, watching videos, listening to podcasts, etc, to properly learn about a thing.
By catering to at least some aspects to these methods of learning, you’ll not only become a better writer of beginner’s guides, but you’ll also solidify your own knowledge about the given subject. You’ll worry about getting things correct so you’ll look up the reference document you’re linking to to make sure you’re explaining the thing correctly. You’ll re-form the same information into your brain when to explicitly define it into words rather than just thoughts in your brain. You might even gain the appreciation for a new perspective.
Perspective
Speaking of perspectives, you have to realize that not a single person has the exact same perspective as you. Otherwise, they wouldn’t need to be reading your guide. If your guide says all the same things that the existing documentation says, then your guide isn’t all that better for beginners, is it?
By taking into account the perspectives of different people you’ll be able to better imagine how someone might get caught in a gotcha or how someone might misconstrue a given piece of information. Thinking in abstract ways is a skill, and not everyone has that skill, so if there’s an abstract concept, try to think of how someone else might not understand it.
Think back to when you were learning about the topic you’re discussing and try to remember the mistakes that you made or the pieces of information that weren’t clear. These are the things that you’ll want to be verbose about. These are the things that you’ll want to take into account when trying to explain them in your beginner’s guide.
Conclusion
Mastering the art of writing beginner’s guides is no easy feat. I’m by no means an expert on the subject. If you’re learning about writing beginner’s guides or thinking about writing one yourself, please search out there for more information than just what I’ve listed here.
This is a good start and you could probably stand to improve your writing with this information, but it’s far from the only tips and tricks that one would need; especially when you’re writing the ultimate beginner’s guide: a textbook.