Handbooks & HelpHub 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

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.

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 GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/. 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.

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 ]
  This is an informational message and uses the “info” short code.

  [ tip ]

  Use the “tip” short code to highlight tips.

  [ alert ]

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

  [ warning ]

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

  [ tutorial ]

  Tutorial lessons should use this shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site.Shortcode A shortcode is a placeholder used within a WordPress post, page, or widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. to insert a form or function generated by a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. in a specific location on your site., 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
• Use Blocks.
  WordPress v5.0 will introduce the BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor (code name GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc.
  https://wordpress.org/gutenberg/). Contents are broken down into individual blocks (image, lists, paragraph, headings etc).  If you are migrating or editing articles that are using Classic Block, feel free to convert them into actual separate blocks.

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, hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., methods, classes, and variables should all be wrapped in the <code> HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. 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.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/.

Layout

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.

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.

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 headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. 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 FTPFTP FTP is an acronym for File Transfer Protocol which is a way of moving computer files from one computer to another via the Internet. You can use software, known as a FTP client, to upload files to a server for a WordPress website. https://codex.wordpress.org/FTP_Clients.

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.

2. Upload via SFTPSFTP SFTP is an acronym for Secure File Transfer Protocol: A standard protocol to move computer files from one host to another over the Internet with enhanced security. to wp-content/plugins/

Open up your favorite SFTP program (FileZilla, for example). Input your SFTP 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.

3. Activate the Plugin

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

AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility)

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.

Gifs

Autoplay of movements are not accessible and it should be possible for users to control animations, videos, sound and so on. 

Following solutions are suggested:

1. Use video instead of gifs. Videos can be controlled by users with play and stop, including going back and forth inside the videos.
2. If videos are not possible and it has to be a gif (for example because the content needs to be make again), provide a thumbnail instead the gif with a play icon and let the gif play, when clicking the play button (and make it also possible to stop it). So it would be possible to consume the gif, but also to read the post calmly with no distraction.

Links

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.

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>