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 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.
The 4 suggested pillars with their own subcategories are:
Get to know the dashboard
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
What has been done
During Google Season of Docs 2020, there was a project to reclassify all the articles, change article titles to follow the new style guide being written at the time and review the content (including links, outdated content, etc).
Due to the rotation of contributors and the team focusing on other issues, the revision of content is still ongoing. If you would like to help out, join a meeting or reach out to @femkreations on 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/, @Femy on Slack and she will guide you.
The new titles and the reclassification has been done. We will continue to include articles that are still to be written, as well as any new article.
The first draft
This is a first draft of the Sitemap and we need your help to make sure articles are in the correct categoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. or if there is anything else we need to add. You can leave your comments on this post or in the Draft of the Sitemap linked above.
What is up for review
Articles classified in the correct category/subcategory
What is not for review
The four pillars (the title yes, but we won’t be adding anymore pillars)
Order of articles under categories nor order of subcategories (we will review them at a later time)
New name titles for articles (these were given during GSoD and have been already reviewed and accepted/rejected by the #docs team)
Other articles written as part of the redesign of HelpHub
In a previous post, we listed the requirements for the new design for HelpHub. This article is going to discuss one particular requirement, the hashtag at the end of the headlines inside an article.
Basically, we want to remove the # character from the headlines. It may be a radical change but it is necessary for accessibilityAccessibilityAccessibility (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) reasons.
First of all, let’s mention the requirements to remove or replace the hashtag. The function must be:
Clear on purpose
Easy to read with keyboard
Reduce visual noise
Not polluting the link’s list for screen readers
# is it an anchor or a link?
The hashtag is used at the end of a headline in the articles as seen in the image below. In order to define its future, we need to understand its behavior.
The hashtag is a link; the anchor is the H2 in the example above. It’s the anchor element, but it’s the link behavior, so it is ambiguous.
Technically, anchor refers to the target of an on-page link. This appears to be a link that gives easy access to identify the URLURLA specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org that will give you access to the current location on the document. That’s…actually kind of complicated.
What about accessibility?
The icon of the character used is not as important as communicating the function of the link. Right now, the # has aria-hidden=true label, so it won’t be read at all.
<h2 id="requirements-on-the-server-side" class="toc-heading" tabindex="-1">Requirements on the server side <a href="#requirements-on-the-server-side" class="anchor"><span aria-hidden="true">#</span><span class="screen-reader-text">Requirements on the server side</span></a></h2>
It’s backed by screen reader text that duplicates the heading title, but is also nested inside the heading; this means that the heading text will be read (e.g.) “Recommended setup Recommended setup”. It’s creating duplicate text nested inside the heading and does not expose any visible text to explain the purpose.
After some research, I have found several options for replacing and/or removing the hashtag.
Adding the link to the heading with a character
Making the heading a link
Replacing the hashtag with a fly-out menu
Adding the link to the heading
Adding the link to the heading, as used by GitHub, where the link is currently the method to expose the link to that section. It can also be linked from the topics table, at the top of the article. We would have to make sure the implementation is accessible to others besides sighted mouse users.
Adding the link to the heading
Adding the link to the heading is reasonable and the simplest solution to replace the hashtag, as it will simplify the problem: the functionality will be clear and the visual noise would be reduced considerably.
There are arguments against providing links that point to themselves, however, as it can make a confusing interaction. One of the arguments against this method is that it pollutes the link list on a screen reader. The way the hashtag is presented now, already pollutes the screen reader’s link list.
Replacing the hashtag
Replacing the hashtag with a fly-out menu, as explained by the w3.org. The w3.org recommends using the fly-out menu to meet WCAGWCAGWCAG is an acronym for Web Content Accessibility Guidelines. These guidelines are helping make sure the internet is accessible to all people no matter how they would need to access the internet (screen-reader, keyboard only, etc) https://www.w3.org/TR/WCAG21/.. The fly-out menu removes the need for multiple page loads. The biggest disadvantage is for people with reduced dexterity who can have trouble or it could be almost impossible to operate fly-out menus,which can be prevented with the correct implementation.
The design above would be changed to meet the 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/ design style.
Removing the Symbol
Is removing the symbol entirely an option?Another recommendation from w3.org is placing the interactive elements in an order that follows sequence. This means adding a table of contents which will link to the interactive element, the headline in this case. Basically, the way it is right now but without the hashtag.
This article is part of the Help Hub redesign series. Previous articles on this project at listed at the bottom.
As previously established, the Help Hub articles have problematic navigation as they are now. There are numerous reasons why that has happened but the new plan focuses on better use of categories.
As of now, there are 9 main categories and some articles have 2 or more categories making the navigation confusing. Another issue is that the landing page does not contain a table of contents per se, instead shows links to some articles.
The plan is to create 4 pillars and add categories to each pillar. Because this work is not done, there will be another post with more details. Let’s talk about the articles.
The proposal for a new navigation includes reading, reviewing, and classifying each one of the 170+ articles on Help Hub plus the articles 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.
What are we reviewing?
Content: what is the article about? wherein the website creation does it fall into?
Codex links: are links still directing to a Codex page? does that Codex page still exists or has been migrated (without updating the link)?
Information: is the feature/process/tool described/recommended still valid or are they outdated?
External links: are links up-to-date or are they too old? is the link directing to a 404? flag all external links for docs team review.
Structure: are there too many links in the same paragraph? is the article following the new style guide (wording, headlines, punctuation, etc.)
Code snippets: are they well structured? is the code complete? are they needed?
Images: is it a good example? is it the latest version?
The revision of articles began as a project under the 2020 Google Season of Docs. The assessment done by the GSoD technical writer included title changes and suggestions of merging/deleting pages with repeated or similar content. @dmivelli also came up with a first navigation proposal.
As a designer, I am reading each article to understand the documentation structure and can propose logical navigation, and at the same time, making recommendations on outdated content, structure, flag links, and image updates.
@atachibana from the documentation team is commenting on my recommendations, finding new links to replace flagged links and revisiting outdated content.
We still need the review of a developer to check on the code snippets and other technical information we are not familiar with.
Before making any updates to the articles, the documentation team will have a chance to have a final assessment.
We are working as fast as we can, but we need help with reviewing. If you are interested in helping to review articles and giving your recommendations, please reach out to @estelaris on the #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.
6:45 pm on March 7, 2021 Tags: Atharva Dhekne, documentation ( 2 ), Google, Google Developers, Google Season of Docs, Google Season of Docs 2020, GSoD, GSoD 2020, Style Guide, tacitonic, WordPress ( 2 ), WordPress Documentation Style Guide
Google established the Season of Docs program to improve documentation for 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. projects while also enabling technical writers to acquire valuable experience with open source organizations and technical writing. My proposal for A Full and Renewed Set of Documentation Style Guide was accepted by WordPress, which was a participating organization in Google Season of Docs 2020.
The reason I chose this project in particular, was that this was one of the only projects in Google Season of Docs 2020 where there was a chance to implement something totally new. An extensive style guide that would govern all WordPress documentation was a testing task that I loved to take on. Additionally, out of all the projects listed on Season of Docs 2020, WordPress had the most suitable project for me in terms of technical proficiency and familiarity with the platform. From the technical aspect, I had been developing websites on WordPress for over 4 years at that time.
I had recently completed a research fellowship with a non-profit organization in open source development and administration, so I was already accustomed to an open source environment. Furthermore, the direct impact of my efforts working with WordPress Documentation were unlike any other organization. Having a direct influence in impacting millions of developers and users is what motivated me to work with WordPress for GSoD 2020.
State of WordPress Documentation Style Guides
The WordPress Documentation Team has been implementing an undeclared but unanimous methodology of publishing guidelines. But once in a while, some elements are presupposed and the process becomes speculative. There didn’t exist any fixed standard and criterion for the purpose of writing and publishing articles for WordPress. The documentation team had written project specific style guidelines, but none that were universally applicable. Most style guidelines that existed were not consolidated in one handbook, or are deprecated and need to be updated. Hence, there was a need to design and develop a unified style guide to standardize WordPress documentation.
Over 40% of the internet’s websites run on WordPress, which in turn indicates that millions of developers and end-users are utilizing WordPress’ impressive functionalities. Documentation is an essential element in assisting these developers and users to efficiently fulfill these functionalities without any hassles, even in case of inconveniences. The overall objective of this project was to standardize a design and style guide, unify existing style guides, and update, as well as append new regulations and specifications for WordPress documentation. This would enable ease of use, simplicity, and uniformity in WordPress documentation.
Tools and methodologies
Before commencement of the project, my mentors and I established that a collaborative platform would be best suited to accomodate the Style Guide. Even though WordPress itself can efficiently manage editing and site administration, we chose GitGitGit is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. and GitHub, as they provide a collaborative platform with a commit history and proper version control. This was especially advantageous as, with WordPress – one of the largest open source communities – come numeorus contributions and thereby various contributors, which would also make the Style Guide future-proof.
The documents were written in Markdown – of the GitHub Flavored Markdown (GFM) variety, and then were parsed by a custom parser for make.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/, courtesy of @coffee2code from the 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. team.
Leading up to the project, I had already started my contributions to WordPress well before the project commencement. I wrote, reviewed, and published various user and support articles for 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/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 (BEE) Documentation team. As a mentor for the WordPress Documentation Mentorship team, I assisted new members and contributors to get conditioned to WordPress’ work protocols and contributing guidelines. Additionally, I also participated at the Virtual Contributors Day at WCEU 2020, and contributed to the WordPress CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress., Meta, and Polyglots communities.
Altogether, these interactions, involvements, and contributions proved to be beneficial for me to distinguish myself as a proficient technical writer, as well as a key contributor and team member that would efficiently complete a project.
During the doc development phase, even though there was no explicit requirement, I made an intention to consistently push commits to the repository everyday for the duration of the project – without diminishing the standard of my contributions. With the exclusion of one day, (December 1, 2020 to be exact – where I lost track of time submitting my Master’s applications :P) I achieved my intention of contributing daily.
These are my daily contributions to WordPress on GitHub (for what they’re worth).
This repository was specifically created for the WordPress Documentation Style Guide and my Google Season of Docs project. Accordingly, all of my commits and issues pertinent to the project can be found on the repository.
Initially, my project was a standard-length project (3 months). 20 days into the project, I realized that there was a lot more to this project than what was my initial idea. As I researched extensively into style guides, dictionaries, and existing documentation, I came across newer topics and articles that needed to be added. Additionally, I had also been spending more time on writing every article than expected.
So, I asked my mentors whether I could extend my project duration from standard-length to long-running (5 months). They coordinated with the respective individuals and officially extended the project to a long-running one.
My main concern towards extending the project was that if the project were to be limited to the standard-length, the essential aspects of the Style Guide would have been left for some contributor after myself. I, having already researched so much into style guides, had a clear path of what else was needed. Moreover, every contributor volunteers their own time to any open source project; there’s no assurance that any individual would commit their time for an extensive project such as this one. So conclusively, I extended my project duration – giving myself more time to complete my deliverables.
Article structure of the WordPress Documentation Style Guide
Even before the community bonding phase, I participated in weekly meetings over SlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. to know more about the functioning of WordPress, the Documentation team, as well as many other teams. During the doc development phase, I provided my weekly updates every Monday during the Docs team meeting. Occasionally the team would also discuss particular elements or articles in the Style Guide which were worth exchanging views about.
I would also clear up issues and difficulties during meetings; or would have them promptly cleared up in async – thanks to my mentors.
There were a fair share of challenges that I encountered during writing the Style Guide. The first thing that I recollect thinking about challenges, is that I could not come up with relevant examples by any means whatsoever. I had my own tribulations while inventing my own examples. But once I referred to relevant documentation, existing handbooks, and support articles, I was comfortable with writing them.
What is imperative for a style guide, I had to spend plenty of time researching into what some might even consider trivial details. A great proportion of my time was dedicated towards writing accurate and unambiguous documentation.
Another challenge was related to the inherent functioning of any open source organization. Though WordPress is one of the largest open source communities, each contributor volunteers their own time to progress the project. You cannot expect and presume that someone would do a task on time as if they were employed by the organization. You have to be accomodating, and you’ll get your tasks done in good time. Regardless, WordPress’ contributors are dedicated individuals who are the benefactors of free and open source software.
Having to build a style guide from scratch, I researched hundreds of pages in style guides, manuals, and developer documentation. Aside from researching, another huge task was to actually design and write the Style Guide. One might say that as a technical writer, you just have to formulate a plan and write documentation. But in the eight months since I started working on this project, I learned quite a lot of things in addition to writing and designing, that normally I wouldn’t have – and rather quite expeditiously.
Just to enumerate a few:
I refreshed my grammar memory and satisfied my appetite for meticulous punctuation.
I learnt a great deal about accessibility, and how most of us don’t even consider how impactful it might be to many individuals.
WordPress is a global project and working with the WordPress community gave me a unique global perspective. I wrote documentation with the likelihood that it would be translated to hundreds of locales.
As is my bland vocabulary, I learnt hundreds, if not thousands of new words by searching for synonyms.
Being probably the last generation that uses fax, I learnt that it is an abbreviation of facsimile.
I explored more music genres and expanded my playlists while writing articles. 😛
I think, in this regard, Google Season of Docs and other open source programs prove to be exceptional avenues in upskilling individuals.
Assign a permanent location for the Style Guide in WordPress docs.
Iron out parser inconsistencies.
Write the remaining articles in the word list and usage dictionary.
Complete internal linking and cross-referencing.
Review regulations that apply across all documentation.
In the immediate future, I plan to continue contributing to new projects and documentation as a team member of the WordPress Documentation Team. As I have earlier, I will also participate in and contribute to other WordPress teams such as Meta, Core, and Polyglots. I’ll continue supporting the Documentation Style Guide in my role as project committer and maintainer.
I sincerely hope that the Style Guide proves to be beneficial for WordPress developers and users alike. Designing and writing the Style Guide for a well-known organization such as WordPress was a unique opportunity, and I would like to thank Google for providing a program and platform for technical writers to achieve these opportunities. I was able to advance my technical writing and write over a 100 articles in a rather brief period of time. I would definitely distinguish this project as successful, and a favourable outcome for both WordPress and myself. The WordPress community has been one of the most affable and engaging communities in open source, and I look forward to a lot more persistent contributions to WordPress.
This is post one on a four-part series. The focus on these series is the redesign of documentation that will include a new template, new categorization, new navigation and some renaming of articles. On this post, we will focus on requirements.
Some of these requirements are very straight forward, others still need a bit of discussion. The links to the PRs are included.
List of requirements:
Article voting (#7) vs feedback: contributions from the public (#240)
SidebarSidebarA sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. navigation styling (#111)
1. Article voting (#7) vs feedback: contributions from the public (#240)
The difference between “article voting” and “feedback: contributions from the public” is the type of information we gather from the user.
Is knowing if an article is useful to a user, better than having the user’s feedback? Is there a way to merge both? Or do we want to keep them both and separate? Or would only one fulfill the documentation goals?
At the moment, there is a feedback form being tried out. The questions are: Was this article helpful? How could it be improved? The reply box is for a long comment and none of these replies/feedback is posted online.
Question is, being that the features require different information and some articles are already too long, do we need both features?
Article voting recommendation
No triggers a feedback box:
And the article will show the number of yes replies
Feedback: contributions from the public (the form that is being tested in WP.org at the moment this post was written)
Are there Rosetta sites that will not be using the HelpHub 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 to translate documentation? Is it still necessary to add the language feature?
Although the dev notes are written for developers, the docs team is interested in keeping an index page of all the dev notes written for a release. The index page will be linked from the release version page.
Feedback section is meant to help contributors report issues such as typos, out of date info, missing facts etc. Even though this feedback is not publicly visible, it is not anonymous. The contributor has to be logged in to send feedback. If logged out, visitor will see the message “Please log in to leave the feedback”.
Where is this feedback visible then?
This feature is enabled on HelpHub and all Rosetta sites with HelpHub enabled.
All the feedback can be found in dashboard’ comments section. It doesn’t really matter if you approve them or not so you can use this status system as a sort of tracking issues system.
We hope this will reduce the gap between new or passing by contributors and the team; and mimic the ease of contributing at Codex.
Complete discussion and the code can be found here: https://meta.trac.wordpress.org/ticket/4915
Our Digital Check-in for this week: Please share the following in the comments:
What did you work on last week?
What would you like to work on this week?
What are your blockers (things that stand in your way of your work) ?
This week is release week:
WordPress 5.6 BetaBetaA pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 1 is schedule for October 20, which starts the beta/rc release testing phase. You can get a preview of the upcoming version via the WordPress Beta Tester plugin
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-partyRCRelease CandidateA beta version of software with the potential to be a final product, which is ready to release unless significant bugs emerge. 9.2 will be published later today (Oct 19) and that is the version that will be merged into WordPress 5.6 coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress..
Gutenberg plugin 9.2 release is scheduled for October 21.
While working on a new design for HelpHub or documentation in 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/, we discovered that the implementation of a menu or a table of contents was difficult because the articles were included in several categories.
Documentation is maintained manually by contributors and it is being moved from the old Codex. The structure is 17 years old and as WordPress develops and grows, the categories that worked 5 or 10 years ago are not necessarily the same that work now.
In order to continue with the design of documentation, we need to define a documentation structure that is clear and fulfills the user’s needs.
Problems with the actual categorization
The issues below affect the way users consult the articles in the documentation section.
There is a lack of definition of user personas.
Search is not user-friendly because navigation is not clear, making article discoverability challenging.
Inside a categoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. with several pages, articles jump order, making navigation confusing.
Some titles are not descriptive enough or use only one word.
What are we looking for
It is important to define first what the goal is for the documentation structure in order to define the categories. Envisioning what our ideal documentation section should look like:
It should be easy to navigate: a user should understand where they are.
Categories should be broken into subcategories to ease mobile navigation.
Categories should be descriptive enough to quickly answer the question: “where does this article go?”
It should be reliable: if an article is not found where it should be, it means that the article simply doesn’t exist
Titles should be descriptive enough for any type of user to understand what the article is about.
Maintenance or updating of the articles should be easy with a clear documentation structure
The structure should allow the incorporation of new categories or subcategories as the software develops.
The docs team worked on creating some stories that can help us verify if the proposed solution will work. You can find the complete list of stories here:
If I am new to WordPress, how do I know if it is the right CMS for my project?
If I am a blogger who receives many comments, is my data secure in WordPress?
If I am not a developer, can I still create a website and add my own branding?
If I am a business owner, can I sell products in WordPress?
If I am a website designer, where can I find information about new releases and upcoming features?
What documentation looks like now
So far, there are 171 articles being moved from Codex into HelpHub. Separately there are new articles being written about 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, so far 40 articles have been added and there are plans for more.
In the image below, we can see a snapshot of how articles are included in several categories. At the moment, the articles were arranged in alphabetical order because the articles jump order while scrolling through the pages:
Let’s review an example from the image above where the articles jump order inside a category with multiple pages.
In the video below, we are looking at the category Getting Started. A session was recorded following the Next Page link at the bottom of the page and then returned to the first page following the Previous Page link. The first page at the beginning has different articles than the first page that we returned to.
What it is like on a computer
The first page begins with the following list of articles:
Appearance Menus Screen
Backing Up Your WordPress Files
Pages Add New Screen
New to WordPress – Where to Start
Administering Your Blog
Resetting Your Password
Creating a Search Page
We navigated to the last page via the Next Page link at the bottom of the page and then returned to the first page, using the Previous Page link.
When arriving to the first page, the list of articles is different from what we have above:
Comments in WordPress
Creating a Static Front PageStatic Front PageA WordPress website can have a dynamic blog-like front page, or a “static front page” which is used to show customized content. Typically this is the first page you see when you visit a site url, like wordpress.org for example.
Users Your Profile Screen
Settings Writing Screen
Giving WordPress Its Own Directory
Settings Reading Screen
What it is like on mobile
On mobile, the situation is the same.
Looking into the future
As mentioned before, the end-user of documentation is not well defined but the existing documentation can shed some light into identifying who the users are.
Who is the content intended for?
From the stories written, we can identify some groups, but we have not explored the many user personas that access the documentation. Here are some examples:
New users looking for a CMS to build a website.
Bloggers/website designers that want to customize a site.
Content creators looking for content to write tutorials/posts.
WordPress consultants that provide services to their clients.
Type of content
In order to define a navigation structure that suits the project and allows for growth, we need to explore information pillars. Pillars shouldn’t be more than 4 or 5, as these can be split into categories and subcategories to form a logical navigation structure. These are suggestions for information pillars:
@kenshino (Jon) have chatted with Matt Mullenweg and he is okay for multi-license setup with a specific reason as long as GPLv2 is the default for all documentation across the WordPress project.
CCO provides a more open domain in comparison to GPLGPLGPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples.. The GPL isn’t necessarily the best for the documentation but it isn’t really explored how that manifests in real-life usage.
Documentation Team members should decide which license will be used. @milana_cap will write the post in p2 for license feedback. @kadamwhite had replied that he was comfortable with GPL for 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/. handbook, but The CLICLICommand Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. handbook is licensed under the MIT.
@Kenshino (Jon) strongly recommends each representative for projects in Docs to chime in Theme Handbook, 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 Handbook, WP-CLIWP-CLIWP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/https://make.wordpress.org/cli/ Handbook etc.
Once the documentation team decides then the documentation team members need to place license info into each logical division of our documentation.
@stevenlinx and @atachibana are working on setting a re-routing codex page. According to the @atachibana, 397 of 1069 (37.1%) code reference for functions pages have been rerouted.
According to the @leogermani, 13 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. have been migrated out of 255 (3.7%) from codex page to the Devhub. It’s really easy task. If anyone wants to help and don’t know how, please 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.” to the @leogermani. @nullbyte was ready to contribute to it.
Policy for external linking
It is a very controversial topic. Few members are in favor to put external links and Other few members aren’t in favor of it.
@milana_cap proposed to allow external links by people who are active in 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/ team members (no companies) in that specific topic.
External links are outdated by time. To monitor them time by time is vast task for documentation team.
@milana_cap will write this up into a coherent P2P2P2 or O2 is the term people use to refer to the Make WordPress blog. It can be found at https://make.wordpress.org/. post and outline the possible routes the documentation team can go.
Workflow for content change approval
All team members are agree with below workflow which has proposed by the @Kenshino (Jon):
Any documentation project member should be able to ask the project rep for review
Any project rep change (not #1 but their own change) – some other project rep or @Kenshino (Jon) can be the second pair of eyes
Tiny grammatical / screenshot changes need not go through this approval process
The workflow will be tracked by appropriate and transparent communications in #docs.
@leogermani said that the i18n section of the plugin handbook is one is very outdated. @themiked will add it to his whiteboard list. There is a need to redirect the localization/internationalization pieces to the 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. It isn’t unique to plugins or themes. The Plugins handbook needs a deeper refactoring.
One of the goals for the redesign of the documentation in 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/ is to create a better search. The best way to do it is by reclassifying all the articles and creating categories with subcategories.
In discussions with the #docs team, we agreed that the best option to do this was by working with a group of people that included developers, documentation, designers and content specialists.
Our goals for the working session were:
Classify documentation articles in categories and provide subcategories if possible
Utilize the already existent categories and perhaps add one or two. The reasoning is that we already have many users that are familiar with it.
Think of the final user: new user to advanced user, not necessarily advanced developers
There are still articles that do not have updated information
Articles should be placed in one categoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging./subcategory, even if the information could be related to other categories
There are unnecessary articles that must be removed. An example of this is the article WordPress Lessons that only offers links to other articles. Once the reclassification is done, there won’t be a need for this type of articles
Revisiting 170+ articles is going to take a lot of time. Some participants from WC Vienna agreed on continuing reading the articles but we will need more people