Difference between revisions of "Wiki Style Guide"

Revision as of 17:33, 12 April 2009

General tone/style

The primary audience of the wiki is the volunteers and staff of Dreamwidth. This is not a wiki for end users.

Some users of the wiki are extremely geeky and very involved with the code and server backend, and we need to respect the very technical level of the wiki pages they use. Other users are very involved in testing and the front end, and their pages can be written in a much less technical style.

Articles should be written as accessibly as possible, keeping in mind the technical level of the subject matter.

Plain language can be used, with a light, friendly style. Please try to avoid colloquialisms as much as possible, as not everyone has English as a primary language.

Wiki formatting versus HTML

There are some things for which I feel it's better to use HTML over wiki formatting:

• Bold and italics (<strong> and <em> respectively)
• Monospace (<tt>)
• Long sections of preformatted content (use <pre>)

This is because it's more accessible to people who don't know as much wiki editing, or because it's cleaner or easier to manage/change.

Things it's better to use wiki formatting for:

• Making lists
• Tables
• Section headings

Variables and paths should have <tt> around them, such as $LJHOME.

Page sections

Pages should be sectioned if they are long enough to warrant it, or if that would help lay out the information better. Sections are delimited like this:

= Section 1 =
== Section 1.1 ==
=== Section 1.1.1 ===
==== Section 1.1.1.1 ===
===== Section 1.1.1.1.1 =====

It's good to start out at the level of ==, just in case you want to reorganize things into more sections later. We prefer spaces in between your ==s and the section title itself, and a line of space before and after each title (unless you have a section at the very top of the page, in which case you can skip the line before).

Lists

Lists should be formatted into unordered, ordered, and definition lists.

Categories

Pages should be categorized, and category tags should go at the bottom of the page, one to a line. A category should look like:

[[Category: Category name]]

That is, the initial category is capitalized, and there's a space between it and the category name.

Templates

Templates are there to help you! Here is a list of templates you can use. They all have instructions for their use if you go to their page.

• There are templates to classify articles needing different kinds of attention: Template:Cleanup (for articles that need reworking of existing content), Template:Expand (for articles that need more content), Template:Update (for articles with outdated or inaccurate content)
• There are templates to offset notable pieces of information: Template:Warn (for important information that can have adverse affects) and Template:Note (for information that should be highlighted in a box to the side)
• When referring to database tables, you can use Template:DBTable to refer to a table and Template:DBField to refer to a field in a table. They'll do all of the tricky formatting to link it up nicely.

Source code

Source code should [Help:Contents#Source_highlighting|be highlighted]].