Style guide

This will learn ya. It will learn ya how to write awesulome pages.

1. Guidelines
2. Notes

Guidelines

Issue: This whole section is quite messy, stylistically. How can it be improved?

Use lower case and hyphens in page links

• RIGHT: /style-guide
• WRONG: /Style_guide

Yes, Wikipedia. You are wrong.

This avoids the xkcd 1167 problem. Oh, and don't use crazy crap in links either. We have proven using science that unicode doesn't work properly in our links. This is sad and we ought to look into this. But don't use full stops or asterisks or anything like that either.

Use secure links when available

• WRONG: http://en.wikipedia.org/wiki/Minecraft
• RIGHT: https://en.wikipedia.org/wiki/Minecraft

Create documents, not conversation threads

• Write in document mode, not thread mode

Use Wikipedia case for headings

• Don't Use Caps Like This

Break up textwalls with structural elements

• Use headings, lists, and links liberally
• Use short paragraphs, long paragraphs, asides, colour, anything to make it more interesting
• Add ornaments like pictures, pull quotes, or text figures

No full stops at the end of list items

• Mother nature just did not intend this

Notes

Admarginal notes. These can be added using custom <span> elements. Just don't press return in a floated span...Issue: Transforming empty blocks dunnæ work.

(Small-caps would be nice, for "Issue".) (I (dpk) use <span class=sc> for this on almost all my sites.))

Should probably check out the diveintohtml5 and diveintopython styles, because they were quite effective at presenting information and yet not being boring.

We keep administrative debris extremely minimal, even eschewing very common metadata such as dates and authors—though that makes sense given that this is a collaborative wiki where pages are updated by multiple people.

Wikipedia-case page titles and headings.

Pull quotes in asides.

Why do we put Tables of Contents at the beginning of a page? You could use them more like an index, and then put a link to them at the top. That's especially useful when the page is quite large and most people would probably want to get straight to the content.

<hr>, magic marker. Actually an aldus leaf here would be nice

Style is mostly a case of monkey see, monkey do. People pick it up from others, rather than reading a guide. So a style guide that people read should concentrate on the middle ground: points that are not common enough that they will be easily picked up in practice, but important enough to warrant noting.