Style Guide
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:
- 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 HTML nicely:
We need to be able to process the content from this Wordpress site and turn it into various formats like LaTeX and EPUB. Our automated tools work much better if pages are formatted with simple and uniform HTML 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 Heading 2 and Heading 3 tags 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>. - Be aware that Wordpress does not always add paragraph tags to your paragraphs.
- Wordpress also tries to replace straight quote marks with “smart quotes”, but it sometimes doesn’t achieve the aim. If you notice weird quotemarks (especially in the PDF version), you can add smart quote marks by hand.