Peeragogy Handbook V1.0/Style Guide

that peeragogy handbook v1.o.really was a life saver.thank u.

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

Maybe this is just a "pet peeve", but I find text very hard to read when there are more than a few bullet points included. For me, it works better when the bullet points are replaced with numbered lists (which should still 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. Therefore, 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!). In particular, it is not entirely pleasant to read a taxonomy. Maybe that sort of thing can be moved into an appendix if we need to have it.

Include activities

In today's live meeting, we agreed that activities would not magically solve all possible usability/readability problems, but they are good to have anyway. And, according to our page layout, each chapter should have at least one activity (linked to from the sidebar). So, when reading the book, please make note of any activity that can be included. (Also make note of problems that won't be solved by adding activities!)

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 when being read (in our handbook or elsewhere). Let's stay conscious of our audience and try to meet that perfect balance of simple, yet professional in our writing.

Additional style bonus points

• Avoid double spaces 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 and the one above are examples!).
• Capitalize the first word of headings and subheadings; lower case all others.