[Writing Exercise] A Guide
There are three components to blogging:
Coming up with ideas.
Organizing your ideas into something coherent.
Writing it in English.
I know lots of people with good ideas and who are proficient at English. Sometimes I encourage them to blog. They write an article and it is awful. The ideas are fine. The English is fine. The structure is an incoherent ramble.
Shaping your ideas into something coherent is a learnable, trainable skill. Mostly it is about selecting the right format. If you’re writing an essay then write an essay. Don’t try to format it into Buzzfeed clickbait. If your ideas want to be a political diatribe then let them be a political diatribe. Don’t hide them in an academic paper. The more writing formats you understand the more prepared you are to pick the right one.
Today’s format: A Guide
A guide tells a beginner how to use a tool or participate in an activity. Guides exist to help people who know but do not know learn how to do . The most important thing about a guide is that reader knows what and are. If a reader thinks they can understand the guide and then discovers halfway through that they are missing a prerequisite then you have messed up. The guide must be comprehensible to anyone who knows .
| post | ||
|---|---|---|
| THE BEST CHOCOLATE CHIP COOKIE RECIPE EVER | basic cooking skills: how to use an oven, how to crack an egg, US units of measurement, etc. | how to bake optimal chocolate chip cookies. |
| My introductory guide to Vim | basic computer literacy | Vim |
| Hy’s tutorial | basic background in programming | Hy |
The Promise
It is best if the reader can determine and from context. The chocolate cookie recipe doesn’t tell the reader what is. It is obvious from a glance at the graphic design. Establishing reader expectations from context is ideal but not always possible. It is acceptable to just tell the reader directly “this guide is for people who know but do not know ”.
This chapter provides a quick introduction to Hy. It assumes a basic background in programming, but no specific prior knowledge of Python or Lisp.
―opening line of the Hy tutorial
The Beginning
Writing should always get straight to the point. The point of a guide is to teach the reader how to do something. Spend as little time as you can get away with explaining what the thing is and why the reader should learn it. THE BEST CHOCOLATE CHIP COOKIE RECIPE EVER doesn’t tell the reader what a chocolate chip cookie is or why you should make one. The reader already knows. The title and introduction tell the reader why to follow these particular instructions.
This is the best chocolate chip cookie recipe ever! No funny ingredients, no chilling time, etc. Just a simple, straightforward, amazingly delicious, doughy yet still fully cooked, chocolate chip cookie that turns out perfectly every single time!
Everyone needs a classic chocolate chip cookie recipe in their repertoire, and this is mine. It is seriously the Best Chocolate Chip Cookie Recipe Ever! I have been making these for many, many years and everyone who tries them agrees they’re out-of-this-world delicious!
Plus, there’s no funny ingredients, no chilling, etc. Just a simple, straightforward, amazingly delicious, doughy yet still fully cooked, chocolate chip cookie that turns out perfectly every single time!
These are everything a chocolate chip cookie should be. Crispy and chewy. Doughy yet fully baked. Perfectly buttery and sweet.
The more your objective is to persuade rather than explain, the longer your introduction will be. Persuade no more than you must. Get to the explaining as fast as you can.
The Middle
A guide should start with the most basic, most important, most frequently-used information. In the case of Vim this is the hjkl keys. The Hy tutorial starts with prefix notation. The cookie recipe starts off with four bullet points.
Soften butter. If you are planning on making these, take the butter out of the fridge first thing in the morning so it’s ready to go when you need it.
Measure the flour correctly. Be sure to use a measuring cup made for dry ingredients (NOT a pyrex liquid measuring cup). There has been some controversy on how to measure flour. I personally use the scoop and shake method and always have (gasp)! It’s easier and I have never had that method fail me. Many of you say that the only way to measure flour is to scoop it into the measuring cup and level with a knife. I say, measure it the way you always do. Just make sure that the dough matches the consistency of the dough in the photos in this post.
Use LOTS of chocolate chips. Do I really need to explain this?!
DO NOT over-bake these chocolate chip cookies! I explain this more below, but these chocolate chip cookies will not look done when you pull them out of the oven, and that is GOOD.
In all three cases a beginner could stop there and leave having learned something useful. The Vim beginner can navigate in Vim. The Hy beginner can write a line of code. The cook can put more chocolate chips in her cookies. A reader should be always be learning something useful. If at any point you are not teaching the reader something useful to a beginner who knows but does not know the reader will stop reading because you are not doing your job.
Don’t get bogged down in details. Legalistic pedantry is for documentation. Too much detail makes things hard for beginners. You are not allowed overgeneralize—misinformation sets your reader up for failure down the road. Just skip over the details.
What constitutes “the basics” tends to be consistent within fields and subspecialties. If you are not sure what the basics are then pick an objective and tell the reader the minimum necessary to competently achieve it.
Use big headings and bold text to emphasize important ideas. A guide should be skimmable. Readers need the option to skip to the next section if they already understand the current section or if they have a learning objective slightly different from .
The End
If you can, the best way to end a guide is to point the reader in the direction of where to continue their education. If you don’t have anywhere to point them then you can just end it abruptly.
Exercise
Write an guide to something you care about. Niche topics are fine. The most important thing is that you pick a topic you already know very well. Guides distill information. The more you know about a topic the more selective you can be about what to include.
Removed.
The best way to determine whether a detail should be included is to extrapolate from your experience teaching people in real life. I have literally, in my entire life, never observed a person ruining chocolate chip cookies by using too high or too low a cocoa content. I don’t even think about cocoa content when making chocolate chip cookies. From this experience I conclude it is not necessary to specify cocoa content. If you think cocoa content is something a reader is likely to get wrong in an important way then you should specify cocoa content.
You should always include all the details necessary for the reader who knows x to perform y competently. What I mean by “[y]ou are not allowed to overgeneralize” is that you should never say anything technically incorrect. Never communicate information that will have to be corrected later.
People who have trouble getting to the point often benefit from a wordcount limit. If you are a rambler then you should enforce a wordcount limit on yourself.
I looked up lots of details when writing my Vim guide. I don’t think requiring details to be remembered off the top of your head without googling is a good rule when writing a guide. On the other hand you should not use quotes unless you can recall the gist of them from memory. (But you should google them anyway to get the words exactly right.)
“No numbers” is a bad rule when writing a guide. Precise language is good. Numbers are the most precise language. Numbers are good. Err on the side of being too specific when writing a guide.