Help:Writing an article
- This page was last modified on July 5, 2011, at 15:21.
From (mt) Community Wiki
This article explains our guidelines for posting an article on the (mt) Media Temple wiki.
Contents |
Page naming
Generic:
Namespace:Action Category Software Error Type on Platform
Sample article titles:
(mt):Add or modify an AccountCenter Contact
(gs):SSH connection
(dv):Reinstall server
(ve):Django with Nginx on Ubuntu
You don't have to include every element shown in the example. And, if a different word order makes more sense, feel free to switch things up. The general rule of thumb is to leave out as many words as you can and still make the title coherent and searchable. i.e., (gs):Set up email account in Apple Mail walkthrough is not as good as (gs):Email settings for Apple Mail.
- The only mandatory part of the article name is the namespace. You can choose from the following:
- (mt) (for AccountCenter generic articles and non-server products like the API)
- (gs)
- (dv)
- (dv) 2.0
- (dv) 3.0
- (dv) 3.5
- (dv) 4.0
- (ve)
- ProCDN
If your article is relevant to more than one server type, make a copy and update your example paths to be relevant to the appropriate server. If you're really not sure where to put it, add it to the MT namespace.
- Action: add, modify, delete, create, install
- Category: email, FTP, SSL, Apache, user, AccountCenter
- Software: Apple Mail, PuTTY, WordPress, FileZilla, Django
- Error: 403 Forbidden, permission denied, not trusted - Use likely search terms.
- Type: information, troubleshooting - If it's a walkthrough, don't include type. Otherwise, it may be helpful to, for example, differentiate Email troubleshooting from the other email articles.
- on Platform: (dv) 3.5, Ubuntu, (gs) Lite - Use this extra designation if an article is for a specific (mt) Media Temple platform and is not relevant to all server types within the namespace category. This is most often needed for (ve) Server articles.
Other title conventions
-
Capitalize only the first word, unless there is a proper name later in the title.
- No: Setting Up Email On Your Blackberry
- Yes: Email settings for Blackberry
- Do not use punctuation. This results in ugly characters in URLs.
-
Do not make the title a question.
- No: How can I edit php.ini on the (gs) Grid-Service?
- Yes: (gs):Edit php.ini
- Use two capital letters for branding, rather than the normal (xx) branding. This, again, is for URLs.
- Make two articles if your article applies to both (gs) and (dv). Update examples in each article as appropriate.
-
Avoid "ing" words. Verbs should be in the imperative tense.
- No: Setting up and troubleshooting formmail
- Yes: (gs):Formmail
-
Use the singular where possible.
- No: Adding and modifying Contacts
- Yes: (mt):Add or modify an AccountCenter Contact
- Use "and" or "or" if the title requires it.
-
Do not include "walkthrough," "instructions," or "how to" in the title. It is assumed that an article in the wiki will be some kind of instructions.
- No: How to configure Outlook
- Yes: (dv):Email settings for Outlook
Page structure
Whenever possible, we would like to adhere to the layout guidelines used by Wikipedia at Wikipedia:Guide_to_layout. Their standards and conventions work very well for technical and how-to articles also.
Supported?
At the very top of every article, there should be a disclaimer with certain warnings for readers of your article if it is not supported or covered by the (mt) Media Temple Statement of Support.
Lead section
The lead section is the section before the first headline. Use this section to give a brief introduction to the content of the article. It is not necessary to included a bunch of links here.
Body
Structure of the article
Here are the guts of the article. Since most of our articles will be "KnowledgeBase" articles it is almost a given that multiple steps will be involved. It is preferred to use ordered lists for outlining these steps. Over time we will have templates for a more preferred look. For now using existing layouts from our imported KB articles will suffice.
More complex articles
If a lot of steps are required for an article it might be better to consider writing separate articles instead. The degree to which subtopics should appear in a single article or be given their own pages is a matter of judgment.
Headings help to make an article clearer, and populate the table of contents; see Help:Section, which users can choose under 'Preferences' to view (the default) or not to view.
Headings are hierarchical, so you should start with
== Header == and follow it with
=== Subheader ===
==== Subsubheader ==== , and so forth.
Just like paragraphs, sections and subsections that are very short will make the article look cluttered and inhibit the flow. Short paragraphs and single sentences generally do not warrant their own subheading, and in these circumstances, it may be preferable to use bullet points.
Between paragraphs and between sections, there should be only a single blank line. Multiple blank lines unnecessarily lengthen the article and can make it more difficult to read.
Images
As a general rule, we recommend using a caption, labeling your image, and including this in your content. For example:
Sudo is a powerful tool. See Figure 1.
The code used to insert the image and caption:
[[File:dadc_sudo.jpg|left|frame|'''Figure 1''': An awesome t-shirt from [http://www.thinkgeek.com/tshirts-apparel/xkcd/dadc/ xkcd].]]
Standard appendices
Certain optional standard sections should be added at the bottom of an article.
Common appendix sections (in the preferred order) are:
- See also
- External links
- Glossary
See also
Here you can have a bulleted list of related articles that are on the (mt) wiki only.
It should be a heading of level 2 so that it appears in the table of contents. For example:
==See also==
* [[(dv):Email settings for Apple Mail]]
* [[(gs):Email settings for Outlook 2010]]
which produces:
External links
Put here, in list form, any web sites that have relevant information for your article including any authoritative sources. Also include a brief explanation where appropriate. Example:
Glossary
At the bottom of your page just above the category links create a Glossary section in a level two heading.
Another bulleted list with the term then a link to the most relevant definition. In most cases a link to an article on Wikipedia or Wiktionary, or some other authorative site is preferred.
== Glossary ==
* term [http://en.wiktionary.org/wiki/term]
* glossary [http://en.wiktionary.org/wiki/glossary]
Produces:
or a definition list with a the most relevant difinitions
: Glossary
:: A list of specialized or technical words with their meanings.
: term
:: A word or phrase, especially one from a specialised area of knowledge.
Produces:
- Glossary
- A list of specialized or technical words with their meanings.
- term
- A word or phrase, especially one from a specialised area of knowledge.
It is preferable to use the linked list method.
Category
'Make sure to place Category links at the very bottom of the article. Please find the proper Category for your article and don't hesitate to use multiple categories either. See Special:Categories for the current list. If a proper category does not yet exist make a new one, while trying to adhere to the style of the current category titles.