Site Conventions
Monospace Blocks
I only use monospace blocks when necessary - when I need multiple lines to line up character by character. The most obvious examples are tab and chord charts, but they are equally valuable for similar tasks. Example:
-w- -w- h -w- -w- -w- h c d e f g a b c
This doesn't always work when inside tables for example:
So we have to make it explicit:
|-|-| |-|-| |
They should not be used for emphasis. Use horizontal rules,...
- ...indents, italics, and bold text instead.
Paragraphs
I find
that
it is hard to read
when people make numerous, one-line
consecutive paragraphs. If you really want someone to read the last line of a paragraph, use italics or bold text.
Relevant Links
I try to include a relevant links section on each page. For lessons, these all have a prev/next link, to view the lessons in order. Additionally, I try to link highly-related content. This doesn't need to be taken to the extreme, though. That's what the categories are for.
Categories
Categories are essentially tags that allow you to find all pages relevant for a single tag or concept. I have a default set of categories that corresponds to the breakdown of the table of contents as well as others that may span a small number of pages. There is no need to make a category that only has 1 member page, unless you plan on there being additional pages that fit the category.
You can see all the existing categories here.
Q/A
I like all my pages to have a Q/A section. This gives kind of a crowd-sourced lesson feel, where as a reader is progressing through the lesson, he may encounter some confusion and can add the question to the Q/A section. Someone with the answer may notice an unanswered question and post the answer. I like making unanswered questions bold to catch more attention and using an unordered list for the questions, with the answer(s) nested underneath as follows:
- Is this a question?
- Yes, it is.
- Is this an unanswered question?