« Back to Peeragogy.org

This is a How-To Handbook.

Keep it short

The easiest sections to read are those that are shorter and include some kind of visual (video or image) and have some personal connection (i.e. they tell a story). For anything longer, break it up into sub-pages, add visuals, make sure each sub-page is accessible to someone (who is it?). Think clearly of this reader, talk to them.

Make it clear

We’ll illustrate this point by example. The original full title of the book was “The Peeragogy Handbook: A resource for self-organizing self-learners”. But “self-organizing” is a technical term, and “self-learner” is a confusing neologism. We shouldn’t use technical terms unless we explain them. So we really shouldn’t use it in the first sentence or paragraph, or title, of the book because we’ll scare people off or confuse them. If we want to explain what “self-organization” means and why it is relevant for peeragogy, then we can take a chapter to do that much later on in the book. At the same time, we shouldn’t try to “say the same thing in a simpler way.” We should try to get rid of the technical concept completely and see what’s left. The easiest thing to do in such cases is to delete the sentence completely and start over: when in doubt, speak plainly.

Don’t overdo it with bullet points

Text can be very hard to read when there are more than a few bullet points included. Numbered lists should also be used sparingly. It also seems that when many disjointed bullet points appear, sometimes the author is really just indexing the main points that are presented better in someone else’s narrative. Therefor, consider replacing an entire bulleted list with a reference to someone else’s book/webpage/chapter. In today’s hyperlinked world, it’s easy enough for the reader to go elsewhere to get good content (and indeed, we should make it easy for them to find the best treatments around!). It is not very pleasant to have to read a taxonomy.

Include activities

When reading, editing or otherwise working your way through the book, please make note of any activities or exercises that come to mind, and share them.  We’re always striving to be more practical and applicable.

Don’t be overly chatty

In our efforts to escape from academia-speak and simplify the text in the handbook, it’s important to make sure we are not heading towards the other extreme – being too conversational. When we’re having a conversation with someone, we tend to pepper our ideas with transitional or pivotal phrases (“In any event,” “With that said,” “As I mentioned elsewhere,” etc.) that help to keep the talk flowing. We also go off on brief tangents before making our way back to the main topic, and sometimes express ourselves in run-on sentences. While this is perfectly natural in speech, it can be confusing and complex in written text. Let’s strive for the perfect balance of simple yet professional writing.

Additional style bonus points

Format your Markdown nicely

We need to be able to process the content from our Jekyll-based website and turn it into various formats like LaTeX and EPUB. Our automated tools work much better if pages are formatted with simple and uniform markup. Some key points: