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:
In order to contribute to any team at 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/, it is necessary to have:
All communication for Documentation team is happening in #docsSlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel. Different parts of documentation are called “projects”. Each of these projects has own rep (team member in charge of the project).
Different projects require different tools so, depending on what you choose, you might need following accounts as well:
If you wish to attend our introduction conference call on the day, you’ll need to use Zoom as well. The account is not needed and you can join the call in your browser or you can download the app. You don’t need camera nor microphone to participate.
Block editor developer documentation – no dedicated maintainer, pingPingThe act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.”@milana_cap or @mkaz for help
Contributor Day will happen online. All instructions can be found here. Besides that, if you registered for WCEU Contributor Day, you’ll receive more detailed instructions in your email on the day.
To help you get started, we’ll hold an one hour introduction on Zoom. In this call we will introduce the team and give you more details on what we were planning to do during the day. If you have something specific you’d like to work on, this call would be a good time to propose it.
The easiest way to get involved is reporting an issue, if you have found one. We have step-by-step lists for reporting issues for every project.
More advanced way for contributing to Documentation team would be fixing reported issues. We still haven’t documented these workflows but you will be provided with assistance by project’s rep. See the full list of reps.
If you need any help or have questions, team members will be available in Slack throughout the Contributor Day.
Contributor Day Facilitators
Documentation team is very friendly and welcoming. If you have any questions whatsoever, do not hesitate to ask. In Slack channel or during Zoom call, someone will answer it before you say “Cookie”.
Besides all lovely contributors to Documentation, we have a list of people who volunteered to give their time and facilitate different Documentation projects during WCEU Contributor Day:
@Sunday Ukafia for onboarding and everything regarding new contributors
@bph 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. editor end user docs
@atachibana for HelpHub (general end user docs) as long as East Asian time zone allows
I will be there the whole day, you can’t avoid that, happily answering all your questions and guiding you to a new directions. We will also see @kenshino there as well.
Office hours, 28 May
Documentation team will hold office hours on Thursday, May 28, 2020, 15:00 UTC. Office hours will be facilitated by @sukafia and you are welcome to ask any questions about Documentation team and how to contribute to various parts of WordPress documentation.
Office hours will be held in #docs channel (WordPress.org Slack account is needed). If you are not able to attend, feel free to ask all your questions in channel and team members will respond as soon as possible.
From May 11-June 8, technical writers are welcome to review the proposed list of project ideas and ask questions related to proposal development. Mentors, thank you for being on hand to help think through project proposals related to our initial ideas or ones the writers may devise. Technical writer applications are due July 9th; We look forward to working with you!
What’s next?
Technical writers interested in working on one of our project ideas, please add your questions as a comment to this post.
Project name: A full and renewed set of documentation style guide Description: We’ve written some style guides along the way but many of those applied to specific handbooks or projects we worked on.
That said, there is not a unified style guide nor is it actually complete.
We propose developing a new style guide while fixing up older ones or simply adopt a great existing one with compatible licenses.
Description: There are plenty of security breaches issues reported. We plan to create documentation of some of the most common issues with suggested fixes so that users can learn and solve their issues.
Related material:
Link to the open sourceOpen SourceOpen Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project that needs documentation – https://wordpress.org/support/article
We can have documentation with two to three attacks issues, explain what effect they have on websites, how to prevent, and the fastest way to fix and protect your website.
Project name: Tracking Doc Suggestions / Updates Description: We do not have a unified tracking system for when a doc needs updates. People do it on MetaMetaMeta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.TracTracTrac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. (which is really for code changes to 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/), report them on SlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/., and sometimes via Twitter. It’s impossible for people to know if a doc is going through updates or is simply outdated. Some projects use TrelloTrelloProject management system using the concepts of boards and cards to organize tasks in a sane way. This is what the make.wordpress.com/marketing team uses for example: https://trello.com/b/8UGHVBu8/wp-marketing. for short term purposes. Some projects use 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/.
We really ought to have a unified tracking system so that we can track these requests and the work to fulfill such requests. And we need to create a process to utilize this system properly.
Project Name: WordPress Development Configuration Guide
Description: Code misconfiguration and setup can introduce security bridges and break security endpoints, thereby leaving the door open for malware infections and cryptographic attacks. Creating a configuration guide or overview for developing in WordPress will be very useful. Some of these exist but are not organized or put together in a single place. For example, the configuration Guide will have several sections as files and directories, debugging, nonces, database, WordPress salt, constants, queries, global vars, htaccess, password, httpsHTTPSHTTPS is an acronym for Hyper Text Transfer Protocol Secure. HTTPS is the secure version of HTTP, the protocol over which data is sent between your browser and the website that you are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all communications between your browser and the website are encrypted. This is especially helpful for protecting sensitive data like banking information., etc.
The configuration guide will be broken down into sections that will address specific issues or setup. For existing resources, they can be referenced accordingly. The main idea behind this configuration guide is to organize WordPress configuration settings into a single base.
Project Name: Curate Existing HelpHub Article To Create Pillar Contents Description: We are continuously creating more content in HelpHub, but basic questions like “Locally Host WordPress” or “How To Secure WordPress”, are answered with separate CPT and not one article to answer completely or links to existing content. While the current configuration is good for SEO, it is confusing for our users. Related material:
I am proposing ‘Pillar Content” that will be curated collection of existing content that will direct guide users in finding more authenticated information. Like “How To Secure WordPress” will give precise guideline and will link and resources from following contents
Project name: Improve Existing Development Documentation and Handbooks Description: We have a lot of developer documentation. CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress.’s documentation is mostly automated.
However handbooks that describe how one would create a theme, make a pluginPluginA 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, use the REST APIREST APIThe REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. or automate things via the CLICLICommand Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. do not receive updated documentation. In turn, this requires that all handbook maintainers know all the changes in each core releaseReleaseA release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software. to be able to write something useful.
In some cases, the handbooks are updated but don’t provide enough examples for new developers to get started. We would like to close these gaps.
Related material:
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 Handbook: https://developer.wordpress.org/block-editor/
Common APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. Handbook: https://developer.wordpress.org/apis/
Description: During the design process, it was discovered that categories are not used to classify documentation articles and an article may have more than two categories instead of using tags to related articles. This makes it difficult for users to search, as they can click on a categoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. > article, and hit the return button only to find themselves in an entirely different category. Another issue is the titles which in some cases do not properly describe what the article is about.
Description: Documentation on developing on top of Block Editor is, depending on the topic, either scarce, outdated, or non-existent. Considering that Block Editor is a significant language leap for WordPress developers, I think the project itself would benefit from having detailed documentation in a form of guides or tutorials, on how to utilize and extend core functionality and what the best practices are.
Features that need documenting: creating custom blocks (basic webpack setup, what plugins are used and why), using editor’s components in custom blocks, using core blocks in custom blocks, using data stores, using all the hooksHooksIn 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., block settings, plugin sidebars, RichText format types etc. Really, everything.
Description: It is not enough to say that creating a WordPress theme is easy if we do not show it in practice in the documentation. Currently we have a good article on how to start with WordPress, I believe we could do more to make the theme development manual better, as it does not provide a kind of tutorial that really ends with the creation of a functional theme.
Related Material:
Link to the open source project that needs documentation: https://wordpress.org/support/article
It can be divided into stages: Creating a 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. template, adding simple styles, separating those from html files and finally converting to one of the templates for the WordPress theme
@atachibana reported that the re-routing of the Codex page to Code Reference functions, 959 out of 1064 (89.7%) have been completed and the remaining functions are associated with tickets or comments and are awaiting approval.
@bph reported that they have 7 contributors working on 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 end-user documentation, @makewebbetter@tacitonic@cguntur have submitted pages awaiting review.
@sukafia reported that they will be taking advantage of WCEU Contributors Day to help onboard new members. He also announced that there will be office hours on Thursday 28th May at 15:00 – 16:00 UTC and encouraged all new members to join in so they can get the necessary guidance.
@sukafia also called for new volunteers for the mentorship team, as they will be needing extra hands.
External Linking Policy
@milana_cap reported that they have decided to make a whitelist of allowed external resources and that a decision on what would be considered trusted and how to deal with existing links (and try to avoid removing them manually) is not yet made.
@milana_cap mentioned that applying the whitelist should be automated. She also mentioned that she will create a p2 post for everyone to share their opinions and questions as comments.
Monthly Coffee Breaks/Zoom sessions
@sukafia shared a doodle link for everyone to vote on the date and time they find convenient for the monthly coffee breaks.
Open floor
@kenshino suggested that there should be a check to see if the current meeting time is the best meeting time for the most number of people.
After deliberations and suggestions from team members, @kenshino concluded that it is best to ask if the current meeting time is convenient for most people and that someone should write a p2 post asking “If the current time is convenient or not” @chaion07 volunteered to work on that.
@kenshino also mentioned that many mentors including himself are receiving lots of messages from Technical Writers and that it will be more beneficial if all queries being answered in one place. So for this, he requested that please all Technical Writers should put all queries either on Season of Docs: Technical Writer Exploration or here in #docs
Please feel free to suggest any changes to the meeting notes by mentioning in comments!
The Make WordPress Teams have a defined structure and a set of procedures. The Meeting plays a vital role in the operation of the individual Make WordPress Teams. These Meetings are scheduled well ahead and has gone through a lot of thinking and consideration before being announced and put on the Official Meeting Calendar. The sole objective of maintaining the Meeting Calendar is not to have meeting times happen simultaneously and creating scope for individual contributors to attend multiple meetings if they want to.
The Weekly Meeting takes place each Mondays at 15:00 UTC. Recently during an Weekly Meeting@kenshino the Official Team RepTeam RepA Team Rep is a person who represents the Make WordPress team to the rest of the project, make sure issues are raised and addressed as needed, and coordinates cross-team efforts. for Docs posed the question
“The current schedule for the Weekly Meeting- Is it convenient or not.”
On that thought we request each and every member of the Docs Team to please respond to following poll options:
Yes
No (Please add suggestions for a better timing)
Please comment below with your response. Very important for us to remember that you need to add a suggestion in the comment below.
@atachibana reported that the re-routing of the Codex page to Code Reference functions, 949 out of 1064 (which is roughly 88.8%) have been completed. He thanked @collinsmbaka and @stevenlinx for their contributions.
@bph is collaborating with @cguntur and @tacitonic to onboard new contributors and testing instructions.
@cbringmann emphasized that they had a fair amount of interest from technical writers. They also added questions as comments to the technical writer post and are requesting a response from the docs team to complete their proposal.
Other questions from technical writers [ @shubhampalriwala, @prubhtej, @tacitonic ] present during the meeting which were diligently answered by @cbringmann.
@kenshino suggested that a mid-step should be done internally. He had raised a few projects for people who didn’t have time to write, but the registered mentors could be reshuffled to choose the right project for them
@kenshino suggested that we should create a post to work this out.
@kenshino read through them and emphasized his general thoughts are, I quote ”in line with our general ethos of the WP project, I’d like to see us being more permissive than restrictive’’ he then suggested a few principles to guide this process as
Our focus should still be on enhancing the official docs / making it complete. So it would make sense for us to encourage people to substantiate our docs with their content first.
If somehow that is not possible or if the external content is useful but not suitable as official information, it’s fine to add external links.
It should be easy for good resources to be listed: We can have trusted sources by default – I’m happy for us to just build that list as we go along.
It should be easy for bad resources to be removed – even if you were once trusted.
Curation is essential – but it does not have to be a day job.
@estelaris emphasized that we need a workflow to avoid curation becoming a day job. @kenshino replied that he hasn’t gotten that far, but agrees that we do need some sort of workflow. @milana_cap once again volunteered to work on it.
Actionable task: Review these function reference pages: link, link, link, link.. and make sure escaping and internationalization are correct and in place.
@estelaris added that they will open new tickets for contributor day, but you need to be registered for the WordCampWordCampWordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. too.
Please feel free to suggest any changes to the meeting notes by mentioning in comments !
Over the last four months, I have been working on the infrastructure, processes, a page inventory, updates on existing pages and new pages for the 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.
There are gaps in the existing documentation with missing pages and existing pages that need to be updated as 80% of them haven’t seen an update since WordPress 5.0 came out. With constant UIUIUI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. changes on for every version, we need more contributors.
It’s time we expand the number of contributors!
The upcoming virtual Contributor DayContributor DayContributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. at WordCampWordCampWordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Europe is a great occasion to bring new contributors on board. Here are some instructions and thoughts for new contributors on how to get started. Your feedback is wanted and you can share your ideas, as well as your questions in the comments below.
Hello, New contributors!
Thank you for volunteering to work on Block Editor End Documentation! My name is Birgit Pauli-Haack. My SlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. username is @bph. PingPingThe act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me on Slack if you have questions or ideas, either publically in the #docs channel or via private message and I will respond quickly, yet asynchronously.
To illustrate our documentation screenshots are essentials. You would need to know how to create screenshots with your own operating system and how to convert them into image to be uploaded to your text.
To shoot basic screenshots, you would need a self-hosted install of WordPress with the latest WordPress releaseReleaseA release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software. (as of now 5.4.1). Many plugins add additional screen properties to the editor or your WP Admin that will confuse user, when they compare your screenshot with their own. If you can’t install WordPress on your computer, most hosting companies allow you to create sites with a temporary URLURLA specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org without increasing your hosting costs. Contact me, if you need assistance with this.
What about Creating Videos?
Videos are not our primary tool to help end users with the block editor. We try to explain everything in writing and with screenshots. However, sometimes it helps to just show how a certain screen option behaves in sequence to augment the written explanation. You see a few very short videos embedded into pages. It’s an enhancement and might not come into play in the first version of your documentation article. Also, the tools are not easily available and require additional skill sets.
First tasks for new contributors
The most immediate tasks is creating new pages for each Embed block of the Block editor. Here is the list in a spreadsheet.
Please select the one block you want to work on next, and enter your information into the respective columns.
Enter your name,
Your email address and
Your Slack user name
Deadline (optional)
It’s not necessary to add a date into the deadline column, although it helps to know approximately when you might find time to finish it. Don’t worry, we won’t hold your feet to the fire. Those dates are approximations, and for me, there are also a way to know when to check in with you and if everything is on track or if there are any blockers.
“If it weren’t for the last minute, nothing would get done.”
Rita Mae Brown
Are we done with the preliminaries? Let’s get documenting!
Share the link to Your Google Doc in the spreadsheet.
Start working on your first page!
As you can see it’s a bit of a set-up, but once you are through the preliminaries (Slack account, Google Account, clean install, Google Doc) you are up and running.
Three Examples: Twitter, Facebook, YouTube
We have three embed blocks already on site, their example might help you decide how deep you can go into your explanations.
When you are done with your first draft, let us know on Slack, and we’ll review it together.
Again, thank you for volunteering to work on the Block Editor End user documentation. We are thrilled to have you onboard!
If you are testing on a self-hosted site, and you can activate the 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/pluginPluginA 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, please add also the Gutenberg 8.1 screenshots for the embed block on the bottom of the Google Doc. With the new WordPress version coming in August we will need to update your pages again to include the new UI. Add the screenshots will give us a head start on those changes.
Disclaimer: This is the first version of these onboarding instructions and you are the first contributors working this way.
Changelog
Updated 2020-05-20
Added a paragraph regarding Gutenberg plugin screenshot to prepare for the WordPress 5.5 changes to come in August 2020.
