Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on 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/
Join our discussions of documentation issues here on the blog and on Slack.
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.
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 ]
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 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.
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.
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>