Difference between revisions of "Wiki Style Guide"

From Dreamwidth Notes
Jump to: navigation, search
(omg I am so OCD)
Line 7: Line 7:
 
There are some things for which I feel it's better to use HTML over wiki formatting:
 
There are some things for which I feel it's better to use HTML over wiki formatting:
  
* Bold and italics
+
* Bold and italics (<strong> and <em> respectively)
 
* Monospace (<tt>)
 
* Monospace (<tt>)
 
* Long sections of preformatted content (use <pre>)
 
* Long sections of preformatted content (use <pre>)
Line 18: Line 18:
 
* Tables
 
* Tables
 
* Section headings
 
* Section headings
 +
 +
Variables and paths should have &lt;tt&gt; around them, such as <tt>$LJHOME</tt>.
  
 
== Page sections ==
 
== Page sections ==
Line 30: Line 32:
  
 
It's good to start out at the level of <nowiki>==</nowiki>, just in case you want to reorganize things into more sections later.  We prefer spaces in between your <nowiki>==</nowiki>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).
 
It's good to start out at the level of <nowiki>==</nowiki>, just in case you want to reorganize things into more sections later.  We prefer spaces in between your <nowiki>==</nowiki>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 ==
 
== Categories ==
Line 46: Line 52:
 
* 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)
 
* 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 [[:Category:Database Tables|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.
 
* When referring to [[:Category:Database Tables|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]].
 +
 +
[[Category: Wiki Management]]

Revision as of 06:03, 10 April 2009

General tone/style

Articles should be written as accessibly as possible.

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]].