Documentation:WordPress Documentation Style Guide

From UBC Wiki

The purpose of this page is to provide guidelines for the writing and design of WordPress Documentation pages on the UBC Wiki.

Page Overview

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:

  1. A short two or three sentence description/lede of page that comes before the table of contents. The lede should not have section headings nor images.
  2. A table of contents; this is usually auto-generated but if not, the __FORCETOC__ command should be used.
  3. The main body of content broken into discrete sections and subsection.
  4. A final section called "See Also" containing both internal links to related WordPress documentation pages and external resources
  5. A category

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

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.

Additionally:

  • The initial letter of a title should be capitalized. Otherwise, capital letters are used only where they would be used in a normal sentence.
  • Titles should not be formatted as questions
  • Do not use a, an, the, what, or how the as the first word (Inserting images, not How to insert images)

Sections and Section Headings

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.

Images

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.

Image Example

Code: 

[[File:WordPress_Dashboard.jpg|thumb|500px|center|The WordPress Dashboard (click to enlarge)]]

Rendering:

The WordPress Dashboard (click to enlarge)

Grammar

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.

Abbreviations

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:

  • UBC
  • UBC CMS

Bulleted and Numbered Lists

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.

  • Use bullet points anytime you have a list of more than two items.
  • Use numbered list for giving point by point directions of how to do something; when sequence of the items is important.
  • Do not leave blank lines between items in a bulleted or numbered list unless there is a reason to do so, since this causes the MediaWiki to interpret each item as beginning a new list.
  • Use the same grammatical form for all elements in a list, and do not mix sentences and sentence fragments as elements.

Categories

Main page: WordPress Documentation Style Guide/Categories

Platform Specific Navigation

For easier navigation, landing pages and infoboxes should be created for individual platforms.

Landing Pages

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.

Infoboxes

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:

Subpages and Platform-Specific Hierarchy

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:

  • UBC CMS Landing Page
    • Plugins
      • Wiki-Embed Plugin
      • Gravity Form Plugin
      • etc.

Transclusion

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.

Mark-up

  • Keep it as simple as possible
  • Use an infobox if there is one; for example: {{Infobox CMS}}
  • Do not use css or html if possible

Links

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.

Renaming pages

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.

Retrieved from "https://wiki.ubc.ca/index.php?title=Documentation:WordPress_Documentation_Style_Guide&oldid=118253"