User:Slide By Mode/Style guide draft

In order to keep the style on this wiki more or less consistent, here's a guide we could follow.

TODO: For now I'm explaining how to do things in wiki markup. I'll try to write about using the visual editor later.

Structure
If there's more than one section, there should still be text in each section. That is, there shouldn't be several headings in a row, there should be at least one sentence between a section header and subsection header.

As a consequence of that, there should also be a lead section before the first level-two header on a page.

Headings
TODO: Explain formatting and add examples

Avoid level-one headings, since those are added automatically. And avoid making "fake" headings using bold or definition lists.

Lists
For lists of terms and definitions, there's definition lists. For other lists there's regular lists, which are formatted like this:

Some languages: Which shows as
 * English,
 * Spanish,
 * German.

If instead of asterisks you put hash signs, the elements on the list will be numbered. Use that for things like steps that should be done in a specific order.

In past versions of MediaWiki, it could cause trouble if there were blank lines within a list. That might not be an issue anymore, but then there's the reverse issue, lists getting merged unless there's some text between them. Just to be sure, avoid having two lists after each other without at least one normal paragraph between them. It's nice to be able to easily see where a list starts and ends.

Also, avoid having images in the middle of lists, since they might cause a list to be split into multiple shorter lists. This could cause things to look fine on a screen but sound confusing in a screenreader.

For more information about formatting lists, refer to MediaWiki's guide to list formatting.

Bold
Words can be written in bold by putting  before and after them, like this:   will show as.

Lead section
A page should contain its title, written in bold, at or near the start. Or in some cases it could be slightly paraphrased.

Examples: For a page called "Splitography": "The Splitography is a hobbyist steno machine, with a split keyboard..."

For a page called "Steno Jig": "Steno Jig is a drilling tool to practise stenography..."

For a page called "Phrasing dictionaries" "A phrasing dictionary is dictionary that single strokes to sequences of..."

For a page called "Systems supported in Plover" "Here's a list of systems for English and other languages:..."

In lists
Sometimes there might be lists where each element has a name and some information about it. If the information about it is a definition or description of the named element, use definition lists, where the structure of each element is a semicolon, a space, the name, a colon, and the description or definition.

Definition lists
If the description or definition is split into multiple lines, the first such lines should be written right below the one with the name, and all lines until the end of the description/definition should start with a colon. For readability while editing, there should be a space after the colons or semicolons, except for colons at the end of lines.

Examples: There's two several types of sounds:
 * Vowels: Sounds that can be the nucleus of a syllable.
 * Consonants: Sounds that can't be the nucleus of a syllable.

Putting newlines inside definitions can be tricky because the software might think the part after them isn't a part of the definition. So despite it looking worse when editing, it's better to keep the whole definition on one line and use  as a newline that displays when rendering the page but not when editing it.

The reason you should avoid actual newlines in the wiki markup is because it translates into something that looks right on screens but might sound wrong in screenreaders. There's several types of sounds:
 * Vowels:
 * Sounds that can be the nucleus of a syllable. They can act as syllables on their own, or go together with other sounds, which will typically be weaker.


 * Consonants:
 * Sounds that can't be the nucleus of a syllable. These can usually not work as syllables of their own, but if they can, they usually don't allow louder sounds to be added to those syllables.

Which displays as:

Regular lists
Use this if there isn't a strong name-definition relationship in each element.

Example: Different languages have different amounts of vowels: Which displays as:
 * Three vowels occurs in languages like Arabic.
 * Five vowels occurs in languages like Spanish and Swahili.
 * Some languages have more than ten vowels, these include Norwegian and Danish.

Images
TODO: when to use them and when not to use them

TODO: Formatting, captions, examples

TODO: How to write alt texts