Welcome to the official home of the WordPress documentation team.
This team is responsible for coordinating all documentation initiatives around WordPress, including the Codex (moving to HelpHub and DevHub), handbooks, parts of developer.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/, admin help, inline docs, and other general wordsmithing across the WordPress project.
Want to get involved?
There are many ways in which you can help the Docs team. Every small contribution counts and helps! You can report an issue or typo you found in the docs, or even help us write new documentation for parts that are still missing. These are some helpful links to find out more about what we do and how to collaborate:
Block Editor Handbook: An overview of documentation contributions of 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. Editor / GutenbergGutenbergThe 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/
Documentation Issue Tracker on GitHub: Submit any DevHub/HelpHub/”Doc Team Handbook” Docs-related issue on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can 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/.
Weekly Meetings
Join our discussions of documentation issues here on the blog and on Slack.
Note:Highlight: Write in a conversational tone that is succinct, natural, and friendly towards the reader.
Always write your documents in simple, easy-to-understand sentences. Voice and tone refer to the mood or attitude of a specific work of writing. Ensure that your voice and tone is succinct, natural, and friendly towards the reader. Avoid a tone that is commanding or too pushy. Try to keep the document contents straightforward and effortless to understand.
Don’t try to be overly colloquial. On the other hand, don’t overdo a professional tone; a formal or robotic tone is unfit as well. Try to achieve a balance between colloquial and formal language, that is suitable for providing knowledge and information. The document should persuade readers, rather than overwhelm them with verbiage.
Even if a conversational tone helps, don’t overplay the humor part. Keep the emphasis on the reader; the reader should not feel out of place. WordPress is a global project, with the majority of users being non-native English speakers. Hence, take into consideration that your document may be translated into other languages. Ultimately, educating and providing information to the reader is of the utmost priority.
Users search through documentation for an answer to a question. Maintain a friendly, informal tone, but focus on being clear and concise in a knowledgeable manner. Get to the point promptly. Explain technical terms, but be careful not to be condescending. To ensure clarity, start by briefly specifying the context of the current topic.
Write user documentation considering that many users are not native English speakers. Avoid long narrative paragraphs; keep paragraphs short and focused, with consistent vocabulary and phrasing that is easy to understand for readers.
Examples
Warning:Not recommended: If you peek over at the left side, you’ll see a menu called main navigation, which is the main menu. This menu is a list of functions you as the administrator can do from the administration screen.
Tip:Recommended: On the left side of the screen is the Main navigation menuNavigation MenuA theme feature introduced with Version 3.0. WordPress includes an easy to use mechanism for giving various control options to get users to click from one place to another on a site. listing the administrative functions you can perform.
Warning:Not recommended: When you visit a website, you probably want the website to remember some information about you so you don’t have to give it the information again. Websites can send your browser this kind of information so they remember you later. This information is called a cookie. I know what you’re thinking, a cookie is something you eat, right? Well, a computer cookie is different. It’s a tiny bit of data used by the website so that when you visit the website again, it gleans things from the cookie like what language you speak.
Tip:Recommended: A cookie is a small piece of data used to remember information about you. When you visit a website, it sends a cookie to your browser, and your browser stores the cookie in a small file. The next time you visit the website, it uses that cookie to get information such as your preferred language.
In most cases, developers are often searching through documentation for an answer to a specific technical question. Maintain a direct and precise tone while writing developer documentation. Use the same tone you would for user documentation, but you can assume a higher level of technical knowledge in your readers. In tutorials, it’s helpful to specify what technical knowledge is being assumed.
For a code reference, be as direct as possible. A conversational tone is less appropriate here.
Examples
Warning:Not recommended: Sometimes you need to get a setting. This is easy if you use the get_option() function and pass in two parameters (a parameter is a value passed to a function). One parameter is the name and the other parameter is a default value.
Tip:Recommended: To retrieve an option, use the get_option() function. It accepts two parameters: the option name and a default value to return if the option does not exist.
Warning:Not recommended: Next, let’s talk about the each method. This method calls a function for each element and returns an array.
Tip:Recommended: The each method calls the provided function once for each element in the array. It returns the original array.