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.
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
- Avoid double lines after paragraphs; this is a leftover from the age of typewriters and can create “rivers” of white space.
- Capitalize the first word of each item in a bulleted list, especially if items include a verb form (this list is an example!). Punctuate uniformly.
- Capitalize the first word of headings and subheadings; lower case all others.
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:
- Mark up your links: use The Peeragogy Handbook instead of http://peeragogy.org. It’s best if the link text is somewhat descriptive.
- Use a numbered list to format your references (see Convening a Group for one example of an article that gets this right!)
- Use hashtags or similar to mark up sections, not bold text. If
you use bold or italics in your paragraphs, you
should check that the markup is actually correct. It should
exactly surround the words that you’re marking up –
<em>like this</em>– and it should not include extra spaces around marked up words –
<em> NOT like this </em>.