Difference between revisions of "Wiki Style Guide"
Foxfirefey (Talk | contribs) m |
Shadowspar (Talk | contribs) (→Templates: +ln: Category:Templates) |
||
| (8 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| + | == General tone/style == | ||
| + | |||
| + | The primary audience of the wiki is the volunteers and staff of Dreamwidth, as well as others who are using the Dreamwidth code. End users probably won't find much of use, but keep in mind everything here is public. | ||
| + | |||
| + | 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 == | ||
| + | |||
| + | ==== HTML formatting preferred ==== | ||
| + | |||
| + | Please use HTML formatting for these tasks, and not traditional wiki formatting: | ||
| + | |||
| + | * Bold and italics (<strong> and <em> respectively) | ||
| + | * Monospace (<tt>) | ||
| + | * Long sections of preformatted content (use <pre>) | ||
| + | |||
| + | [[User:Foxfirefey|Foxfirefey]] feels it's better to use HTML over wiki formatting for these things 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. | ||
| + | |||
| + | ==== Wiki formatting preferred ==== | ||
| + | |||
| + | Things it's better to use wiki formatting for: | ||
| + | |||
| + | * Making lists | ||
| + | * Tables | ||
| + | * Section headings | ||
| + | |||
| + | Variables and paths should have <tt> around them, such as <tt>$LJHOME</tt>. | ||
| + | |||
== Page sections == | == 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: | 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 == |
| − | === Section 1.1.1 === | + | === Section 1.1.1 === |
| − | ==== Section 1.1.1.1 === | + | ==== Section 1.1.1.1 === |
| − | ===== Section 1.1.1.1.1 ===== | + | ===== Section 1.1.1.1.1 ===== |
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 == | ||
| − | Pages should be categorized, and category tags should go at the bottom of the page. | + | Pages should be categorized, and category tags should go at the bottom of the page, one to a line. A category should look like: |
| + | |||
| + | <nowiki>[[Category: Category name]]</nowiki> | ||
| + | |||
| + | 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 [[: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. | ||
| + | * The [[:Category:Templates]] page lists all templates that currently exist. | ||
| + | |||
| + | == Source code == | ||
| + | |||
| + | Source code should [[Help:Contents#Source_highlighting|be highlighted]]. | ||
| + | |||
| + | [[Category: Wiki Management]] | ||
Latest revision as of 14:34, 4 June 2013
Contents
General tone/style
The primary audience of the wiki is the volunteers and staff of Dreamwidth, as well as others who are using the Dreamwidth code. End users probably won't find much of use, but keep in mind everything here is public.
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
HTML formatting preferred
Please use HTML formatting for these tasks, and not traditional wiki formatting:
- Bold and italics (<strong> and <em> respectively)
- Monospace (<tt>)
- Long sections of preformatted content (use <pre>)
Foxfirefey feels it's better to use HTML over wiki formatting for these things 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.
Wiki formatting preferred
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.
- The Category:Templates page lists all templates that currently exist.
Source code
Source code should be highlighted.
