The purpose of this page is to provide guidelines for the writing and design of WordPress Documentation pages on the UBC Wiki.
WordPress Documentation pages should be kept as precise and as short as possible. Each page should only cover a single, specific topic. Furthermore, each WordPress documentation page should have roughly the same structure. The common items every page should have (and in the order they should have it) are:
If the topic that a specific page covers could be relevant to multiple platforms (UBC Blogs AND UBC CMS) that page should be kept free as possible from specific platform labeling so that it may be easily transcluded across platforms.
Titles should be as short and as descriptive as possible. They should also be consistent with the titles of pages that cover similar topics. If the article or page being created is a subpage, it should not repeat descriptors.
For example, the following would be an imprecise title: Documentation:Wordpress/How to use Wordpress Shortcodes. A better title might be: Documentation:WordPress/Shortcodes.
WordPress documentation pages should be broken into multiple sections as it makes the page easier for users to scan and find the specific content for which they are looking.
Section headers should always start at the h2 level (==example==) and subsections should follow hierarchically (h2 --> h3 --> h4 --> h5). If a section contains lots of subsections, that section should be broken into multiple sections.
When possible, annotated screenshots demonstrating a process or concept should be inserted into the page. When uploading images, the file name should be descriptive (for example: WordPress_Dashboard.jpg).
Images should be added as "thumbs" and have a width of 500px.
They should have a brief caption, including the phrase "(click to enlarge)". In general, images should not be wrapped by text. Instead, alignment should be either be "none" (which will create an left alignment with no text wrap) or "center" (which creates a center alignment with no text wrap).
WARNING: If there's an infobox on the page that the image is being added to, avoid having "thumb" images "center" aligned as this may cause a stylistic error on smaller/mobile browsers. The result is that the image and the infobox will overlap (usually with the image blocking all of the infobox's content). This is only likely to happen if the infobox and the image are around the same position on the page, so if the image is far below or above the infobox there should be no problems. In any case, test different browser sizes if unsure whether something may break if resized.
[[File:WordPress_Dashboard.jpg|thumb|500px|center|The WordPress Dashboard (click to enlarge)]]
Language should be neutral and have a semi formal tone. When using the second person ("you"), the actual use of the word "you" should be minimized. For example: the sentence: To upload an image, you first click on the image icon should be written To upload an image, first click on the image icon.
When an abbreviation is to be used in any article, give the expression in full at first, followed immediately by the abbreviation in parentheses.
For example: You may use WordPress (WP) to create both blogs and full web sites.
This is not necessary for:
In general, bullet points and ordered lists should be used often as it is often easier for a user to parse a list than it is to parse a block of text.
Main page: WordPress Documentation Style Guide/Categories
For easier navigation, landing pages and infoboxes should be created for individual platforms.
Each platform should have a structured "landing page" that serves as a table of contents for all of the documentation relevant to that specific platform. For example UBC Content Management System is the landing page for UBC CMS. These landing pages should be constantly refined to make it easy for users to find content.
Navigation infoboxes should also be created and used to help users find the proper help pages. These infoboxes should be refined as content pages continue to get built out. The infobox should be placed on the majority of platform documentation pages. The exception would be for pages that are image heavy, the addition of an infobox can make a page overly complex and hard to read. In those cases an infobox should not be used.
Currently, the following WordPress Documenation infoboxes exist:
Documentation pages that relate to a specific platform should be structured in a way that is logical and helps the user navigate to the information they need. "Generic" WordPress pages should be transcluded into an appropriate platform specific context. Ideally, each general topic should have a specific overview page and multiple subpages. For example, a hierarchical structure might look like the following:
When possible, WordPress documentation pages should be kept free of platform branding. Before creating a new page, the existing WordPress documentation pages should be searched for already existing pages on that topic. If it is important that the topic be placed within a specific context (as part of a platform page, as part of a training session page, etc), rather than copy and pasting, or recreating, the content, it should instead be transcluded.
Each documentation page should have internal links to relevant WordPress documentation pages (for example the word dashboard can be linked to go to the appropriate page). If you are linking to an external resource, describe the the link, for example: WordPress.tv offers webcast tutorials.
After renaming a page, go back to the old page (which should now be a redirect) and use the what links here function (first link in the toolbox), and update the existing links so they go directly to the new page title.