Handbooks Style and Formatting Guide

In order to maintain consistency across the handbooks, please follow this style guide. The aim of the guide is to help you to create documents that are readable and useful to all readers. Advanced users should be able to scan the document and pick out what they need. But you still need to include the detail to help novice users.

Style Style

Write in an informal but knowledgeable manner. The reader should feel that this is a friend explaining something clearly to them.

Explain what you need to in as few words as possible.

Always write in the second person, i.e. you, not we, addressing the reader as though they were sitting beside you.

Correct

Log in to your WordPress Admin Screens.

Incorrect

Next, we need to log in to WordPress.

Top ↑

Content Content

Stick to one topic per article. Don’t diverge into other topics, but link to them where relevant.

Example

This article will show you how to get started contributing to WordPress via Github. Before you get started, you’ll need to have a local server. You can learn how to do it in this article on installing WordPress locally.

When writing articles, stick to one major point per paragraph. This will help to maintain the clarity of the document. A good idea is to plan out what you’re going to write beforehand by writing down each point you want to make.

Top ↑

Formatting Formatting

  • Use bold to make important points stand out or to indicate instructions: e.g. Navigate to Pages > Add New
  • If you want to alert the user to something, use the following short codes:
    [ info ]

    Note: This is an informational message and uses the “info” short code.


    [ tip ]

    Tip: Use the “tip” short code to highlight tips.


    [ alert ]

    Alert: The “alert” short code is for alerting readers to important messages.


    [ warning ]

    Warning: When something is particularly precarious, use the “warning” short code.


    [ tutorial ]

    Tutorial: Tutorial lessons should use this shortcode, but must continue on from previous tutorials.

  • Use ordered and unordered lists
  • Use heading tags in the correct order from h2 – h6
  • When referring to menu items, use the format Pages > Add New

How to deal with file names:

[preserved_text 5ce7c31ec4642f252291d006cfc6097c /]

To insert code examples, wrap the code in the correct shortcode. For example:

  • [php][/php]

  • [html][/html]

Functions, hooks, methods, classes, and variables should all be wrapped in the <code> HTML tag and properly linked to the code reference. Links should start inside the code tag.

When a page is complete, there should be no links to the Codex, unless the document does not exist on developer.wordpress.org.

Top ↑

Layout Layout

Images Images

Images should be full size. Don’t include thumbnails that readers have to click on to see unless absolutely necessary. To take screenshots that look great, resize your browser window. By resizing down, you can take screenshots of the specific areas of the screen that you are referring to.

Top ↑

Articles Articles

Avoid huge chunks of text. Make your article paragraphs short and to the point. Use headings where relevant to make it easy for people to scan.

Top ↑

Tutorials Tutorials

Tutorials should always be written in a clear, logical fashion. You should do the following:

  • Have an introductory paragraph that tells the reader to what they will do.
  • Include a list of anything that they will need.
  • Each step should have one clear task.
  • Each step should have a header that states concisely what the task is.
  • Each step header should be numbered and wrapped in the appropriate heading tag.
  • Where relevant, include screenshots.

The following example demonstrates a simple tutorial for downloading BuddyPress and uploading to WordPress using FTP.

1. Download BuddyPress & Unzip

Navigate to the WordPress plugin repository and download BuddyPress. Unzip to a folder that you can easily find on your computer.

A screenshot of the BuddyPress download button

2. Upload via FTP to wp-content/plugins/

Open up your favorite FTP program (FileZilla, for example). Input your FTP login details. If you do not have these, you will be able to get them from your web host.

Once you are logged in to your server, navigate to wp-content/plugins/. On your local server, locate the unzipped BuddyPress folder. Drag and drop the folder to your remote website.

A screenshot of Filezilla. An arrow points from the files on the local server to the remote server

3. Activate the Plugin

Log in to WordPress. Navigate to Plugins. Locate the BuddyPress plugin and click the activate link.

A screenshot of the activate plugin button. Activate is highlighted

Top ↑

Accessibility Accessibility

Images Images

Try to keep in mind that not everyone will be able to see your screenshots or other explanatory images. So please do not rely on them too heavily.

Top ↑

When creating link text, be aware that links can be rendered out of context in some user agents (e.g. the Links List in the JAWS screenreader). So avoid generic text like “here” or “this”, and ensure that link text describes the resource that you are pointing to. On pages that contain multiple links, ensure that each link text is unique – unless you are linking to the same resource in more than once place.

Top ↑

Abbreviations Abbreviations

Avoid the use of jargon, abbreviations and acronyms whenever possible. If you really do need to use an abbreviation, use the full, expanded version first, followed by the abbreviation in parentheses (brackets). Alternatively, use correct abbreviation markup such as:

<abbr title="World Wide Web Consortium">W3C</abbr>