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.
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 GithubGitHubGitHub 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 be 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.
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 shortcodeShortcodeA 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., 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 Block Editor (code name 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.
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.
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.
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.
2. Upload via SFTP 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.
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:
Use video instead of gifs. Videos can be controlled by users with play and stop, including going back and forth inside the videos.
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.
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.
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>
First published
Last updated
4 responses to “Handbooks & HelpHub Style and Formatting Guide”
As per sewmyheadon’s suggestion, here are my suggestions for additions:
We need a specific style for emphasis boxes, sidebars, etc. A suggested style similar to boxes currently on the Make site: <div style=”border: 1px solid #CCC;background: #F1F1F1;padding: 0.7em 1em;”> For sidebars add the following: float: right; width: 45%; margin-left: 2em; OK to reverse left for right where warranted.
It can be interpreted to start article section heading tags at h4 as written. Actually starting at h2 will work fine, the article title h2 (not h3!) is styled with 2em and section h2 is styled with 1.8 em, so at least visually this works, leaving more levels for sub headings before styling hierarchy, contents listing, skip links etc. stop being applied. H5 and lower do not have any such features applied. For complex articles with several levels ideally we should extend the CSSCSSCSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site.. In the interim I’ve been using this workaround:
For h5 leave as is
For h6 add • <em>
For h7 add  ·
For h8 add   ◦ <em>
For h9 add    -
(My articles actually only get down to h6 at most, the rest is conjecture)
For inline code examples use teletype (tt) style. The code shortcodes ( [php] etc.) are great but are only practical for blockBlockBlock 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. level code or references to the Codex function reference. Filenames already use the HTMLHTMLHTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. code style and actual inline code examples should be styled differently than file and path text.
All filterFilterFilters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. and action tag references should be italic (em) style in single quotes. Tags containing variable elements should be double quoted to reflect PHPPHPPHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php. quote usage where only double quoted variables are expanded: “manage_{$post_type}_columns”
For proper image sizing the basic column width should be noted. On this site it is 700px. Inline images should be this width or major fractions (1/2, 1/3) of it to avoid links to larger images. Only use larger linked images when needed to accurately present the contained information.
Image captions should be sentence voice and case, not Title Voice and Case.
Link title attributes should be defined following consistent guidelines. This is what I’ve been using:
skip links “Page Section”
to Handbook “Handbook Chapter”
to Codex “Codex Reference”
to jQuery.com “jQuery Reference”
to PHP.net “PHP Manual”
to non wordpress.orgWordPress.orgThe 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/ sites “External Site”
If desired, append a more specific tag preceded with a spaced hyphen: “PHP Manual – date()”
I don’t care if you go with my definitions or something else. I would definitely like to see something defined for these elements. I am encountering them regularly in my writing and would rather format the elements correctly the first time rather than everyone needing to go back and change everything after the fact because this was not defined early enough. My only real goal here is for format consistency throughout the handbooks while avoiding the need to go through everything after the fact in order to achieve it.
I wasn’t sure how much markup or down I could use here in comments (nor that I could edit), so the presentation is crude. I hope it can be deciphered adequately. Being an editor, I’m willing to do the actual editing along with examples and screen shots as needed in the actual page regardless of what you all decide, just let me know what that is and I’ll get it done. I promise it’ll look better than this comment 🙂
4 responses to “Handbooks & HelpHub Style and Formatting Guide”
Is there a standard for annotating images? For example, do you always use red text and arrows? What about putting in text on the annotations?
[…] Read the Handbook Style Guide […]
As per sewmyheadon’s suggestion, here are my suggestions for additions:
We need a specific style for emphasis boxes, sidebars, etc. A suggested style similar to boxes currently on the Make site: <div style=”border: 1px solid #CCC;background: #F1F1F1;padding: 0.7em 1em;”> For sidebars add the following: float: right; width: 45%; margin-left: 2em; OK to reverse left for right where warranted.
It can be interpreted to start article section heading tags at h4 as written. Actually starting at h2 will work fine, the article title h2 (not h3!) is styled with 2em and section h2 is styled with 1.8 em, so at least visually this works, leaving more levels for sub headings before styling hierarchy, contents listing, skip links etc. stop being applied. H5 and lower do not have any such features applied. For complex articles with several levels ideally we should extend the CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site.. In the interim I’ve been using this workaround:
For h5 leave as is
For h6 add • <em>
For h7 add  ·
For h8 add   ◦ <em>
For h9 add    -
(My articles actually only get down to h6 at most, the rest is conjecture)
For inline code examples use teletype (tt) style. The code shortcodes ( [php] etc.) are great but are only practical for 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. level code or references to the Codex function reference. Filenames already use the 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. code style and actual inline code examples should be styled differently than file and path text.
All filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. and action tag references should be italic (em) style in single quotes. Tags containing variable elements should be double quoted to reflect PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php. quote usage where only double quoted variables are expanded: “manage_{$post_type}_columns”
For proper image sizing the basic column width should be noted. On this site it is 700px. Inline images should be this width or major fractions (1/2, 1/3) of it to avoid links to larger images. Only use larger linked images when needed to accurately present the contained information.
Image captions should be sentence voice and case, not Title Voice and Case.
Link title attributes should be defined following consistent guidelines. This is what I’ve been using:
skip links “Page Section”
to Handbook “Handbook Chapter”
to Codex “Codex Reference”
to jQuery.com “jQuery Reference”
to PHP.net “PHP Manual”
to non 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/ sites “External Site”
If desired, append a more specific tag preceded with a spaced hyphen: “PHP Manual – date()”
I don’t care if you go with my definitions or something else. I would definitely like to see something defined for these elements. I am encountering them regularly in my writing and would rather format the elements correctly the first time rather than everyone needing to go back and change everything after the fact because this was not defined early enough. My only real goal here is for format consistency throughout the handbooks while avoiding the need to go through everything after the fact in order to achieve it.
I wasn’t sure how much markup or down I could use here in comments (nor that I could edit), so the presentation is crude. I hope it can be deciphered adequately. Being an editor, I’m willing to do the actual editing along with examples and screen shots as needed in the actual page regardless of what you all decide, just let me know what that is and I’ll get it done. I promise it’ll look better than this comment 🙂
@bczworkz ‘s writing will appear very bland to read, but actually he/she did a good time investment behind it.