Welcome to the official home of the WordPress Documentation Team.
This team is responsible for coordinating all documentation initiatives around WordPress, including the handbooks and other general wordsmithing across the WordPress project.
Want to get involved?
Start here to find out more about what we do and how to contribute:
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 by the repository owner. https://github.com/
Weekly meetings
Join our discussions of documentation issues here on the blog and on Slack.
Please review the issues here as the team will be discussing them during the meeting on March 5.
Consider adding introduction to what is included in the documentation site
The conversation can be followed in GitHub. The proposal is to add a tagline to the headerHeaderThe header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. and there are some good proposals there. This needs to be decided quick as 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 is getting ready to finish the redesign.
Documenting the Playground for end-users
@zieladam has some ideas to include Playground documentation in HelpHub. The idea is to create use cases for now.
The use cases and recommendations are written in the User Documentation ticket in the GH Playground. Once a docs contributor is interested in working on these articles, we can transfer them to the docs/issue GH.
During the recategorization of the documentation, the team removed several articles that were developer-focused or included a lot of developer-jargon. All these articles are now part of the Advanced Administration Handbook and will be removed from /documentation/devhub/.
The redirects have been applied as indicated in issue #59. Some articles have been merged to provide better explanations. Although, the maintenance is still ongoing, most of the articles have been updated.
There are several ways to find information regarding the features or issues in WordPress and each one of them has a function and a time. This is a short explanation of what each means, the difference and when to use them.
What is what?
A good way to differentiate them is to define them and to provide use cases for each. None is better or worst than the other neither is any more or less important. It all depends on when they are used.
Support is 1:1, requires interaction and it is used for more urgent issues, whether is a chatbot or person and is immediate.
Forums are intended for broader help or best advice on specific topics. Most of the time is asynchronous but is monitored by a team or person, paid or volunteer. Most importantly, forums are community driven.
Documentation are basically instructions on how to do things. There is no interaction of any kind for questions. Literally, “what you read is what you get.”
Training creates lessons on topics. These can be on video or written form. Can be individual or part of a series. And training can be immediate or in the user’s own time.
Some use cases
Users require information for different reasons and search for it in different ways.
For instance, hosting companies use support, either by chat or call, to resolve a user’s issue. Whether is urgent or not, it usually is something that the user cannot solve by themselves or it has an immediate need for solution.
The forums are topical and in threads. They are very useful for discussions and to provide guidance over an issue or topic. Forums are monitored and conversation are mostly asynchronous. Some of the uses could be a school discussion group, product sales, best practices, product help, product how-to’s, etc.
When a user wants to learn fairly quick how to do something, following the steps in a documentation article is the best way. There are no interactions and the user reads it in their own time.
In opposition to wanting to deeply learn about a subject, then the user would search for a training lesson or course.
What can a user find 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/
WordPress.org does not provide support. There is no team that will reply to questions 1:1 at any time. Instead there are the Forums that are monitored by contributors, volunteer and paid, that reply to questions posted.
There is documentation for end-users and developers and there are training lessons offered in Learn.
It is a strong recommendation by the documentation team to stop using the word support and instead refer to each instance with their respective name.
Props to @milana_cap and @atachibana for the review of this article.
With the feedback received last week, the design team worked on a second iteration in Figma. If you haven’t given us your feedback, please do so in this file. Feedback will be open until December 2, 2022, as we want to proceed with the work.
What is the new look about
With all the redesign happening in WP.org, it is now time for Developers documentation. The design team has started with a new look but need feedback from documentation users.
Developers documentation is composed of handbooks and articles. At this time, the handbooks will not be redesigned.
What we need feedback on?
Compare and review the landing page. Changes include:
First 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. links the handbooks under Developer Reference
The second block splits the Code Reference into New and updated in 6.x version and the Common APIs handbook TOC
The link to Dashicons was removed since they have been deprecated. Do they still need to be linked under Resources? Or shall the link move to somewhere else?
Does this navigation make sense?
Other sections that need review
Breadcrumbs have been moved to the blue ribbon
User contributed notes
User contributed notes feedback form
Styling in the code block (highlighting the title and keeping the code background white)
The general Add note/feedback form
The changelog at the bottom of the page will be expandable
Feel free to leave your comments in the Figma file or in this post.
Props to@joen for feedback on this post and @javiarce for his design work.
Note-taker & Facilitator selection for Next Meeting
Projects checks
Alterations on HelpHub design pages to sync with new WP.org template
Changelog is a collapsible item
Changelog and Feedback form switched placement
Adding descriptions to categories & subcategories on landing page, will affect mobile length
Adding description to articles in categoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. page (no description on subcategory) – will affect mobile length
Article content switch sides, long content to the left and article TOC to the right
Atharva Dhekne
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.
Project description
Synopsis
WordPress is a global non-profit software organization that is dedicated to serving the global community with software that emphasizes 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), performance, security, and ease of use. WordPress’ cause strives to democratize publishing and open source software on the web. In our digital age, a website is quite literally the online facade of an organization or individual; and WordPress serves an immense task of efficiently serving hundreds of millions of users – attributed to the 40% of the internet it runs – with their software. To further efficiently serve these users, documentation proves to be essential and is used by most developers, administrators, and end-users. Therefore, documentation can be established as a principal factor of the WordPress ecosystem. At the time, WordPress documentation didn’t include a universal and unified set of rules and style guidelines for publishing. The motive of this project was to create a full and renewed set of documentation style guidelines, universally applicable for WordPress documentation. The project idea involved consolidating all aspects of design and style guidelines like semantics, syntactics, grammar guidelines, punctuation, development-specific rules, design attributes and formatting specifics. It also incorporated language conventions like voice, tone, tense, all parts of speech, as well as naming conventions. The tools, languages and platforms used were WordPress, 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 by the repository owner. https://github.com/, Markdown, 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., MySQLMySQLMySQL is a relational database management system. A database is a structured collection of data where content, configuration and other options are stored. https://www.mysql.com/., 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./CSSCSSCSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site., and JavaScriptJavaScriptJavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/..
Project plan
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.
Objectives
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.
Implementation
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.
Contributions
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.
Challenges
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.
Peculiar learnings
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.
Future prospects
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.
Conclusion
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.
I’ve recently volunteered to be 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/ developer documentation 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..
Here are some aspects that I thought the team could focus its discussions and reflections to get started.
Where are we at now?
It is essential to have an overview of existing documentation. Both the one present on https://developer.wordpress.org/block-editor/developers, on GitHub (if there is any), and also those in progress. This is to avoid dispersing our efforts, and to take advantage of the work already done by other contributors and volunteers.
What should be included?
In my view, one of the first step would be to agree on what should be included in the new documentation. There are currently many concepts (CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. concepts, APIs, etc…) that can be useful for developers using 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. Some of them are already present in the current documentation. Others are in the codebase on the project’s 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 by the repository owner. https://github.com/ repository.
A new structure?
The current structure of Gutenberg’s developer documentation is one of the aspects that makes it not friendly at all. For example, the home page of the documentation starts with the chapter “Creating Blocks”. A beginner is like thrown into the cauldron without knowing the prerequisites. Several contributors also address the question on GitHub here https://github.com/WordPress/gutenberg/issues/22151.
In this regard, I think we could learn from examples of documentation such as Gatsby.js https://www.gatsbyjs.org/docs (a quick start/tutorial, then a reference guide that discusses key concepts in a more or less defined order).
Cross-team collaboration
How do we want to collaborate with the different teams to make this happen? From here I see the core-editor team playing an important role, given their experience with the block editor development.
What’s next?
At this stage, we are only at the discussion stage, to see what is feasible and the best way to do it. If you are interested in helping with any of the steps, please feel free to comment. Also, if you have other points that you think are essential or need to be discussed in this plan, please feel free to mention them in your comments.
Season of Docs 2020
With the Season of Docs starting in a few weeks, I think this could be a great opportunity to move forward on that plan.
There are two projects in particular that could help:
Project #6 with @kenshino: Improve Existing Development Documentation and Handbooks and
Project #8 with @milana_cap: Extending Block Editor.
@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.
This discussion started in Slack during one of Docs team meetings. It was discussion about the best tool for tracking progress and issues 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 documentation. However, the question of tool is widely applicable to all Docs projects, hence the need for this post and discussion.
Having complete documentation on Codex made contributing to Docs team easy in a way that everyone, as long as logged in, could modify existing or add completely new parts of it. However, this method had its flaws. It was impossible to track which parts of documentation were modified. And if we can’t track modifications then we can’t check the correctness of newly added information as well as the quality of code examples.
It took few years but we moved big parts of Codex to new places, built on WordPress. While we have more control as complete content goes under our review, this move made contributions to documentation team fairly difficult. The process itself is unclear, different Docs team’s projects use different tools (none of which covers all we need) but the common scenario we end up with is people reporting issues in SlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.#docs channel.
The Tools
Documentation team uses several tools in contributing process. We have several Trello boards with more or less activity. Also, progress for almost all projects is tracked in Google Docs.
Contributing to code reference can be done with code examples through User Contributed Notes (e.g. User Contributed Notes for activate_plugin() function) or with inline documentation via Core Trac (which is more CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. than Docs team’s responsibility).
We also have Documentation Trac available. It hasn’t been used for anything before.
What is the problem?
Different projects have different workflows and, therefore, different tools. However, we have several problems to solve:
Access – while we do welcome everyone to contribute to Docs team, we also need to be careful with giving access to handbooks hosted at wp.org. If we want to make sure that only curated info gets into handbooks we need to limit access. That also means that whole burden of reviewing and maintaining handbooks falls on these few people who have access.
Keeping track of contributions and contributors – the easiest way to keep track of contributions/contributors is to use tools we have available at wp.org (TracTracTrac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. and Slack). On the other hand, Trac is not the most intuitive tool for wider range of WordPress users and Slack tends to burry information so the history is lost in tons of archives. Also, in some cases it is important that we have a history of a decision/discussion available at one, easy to access, place.
Project managing – each project is different but it is a project nevertheless. It is important that the tool we use for it have project managing features which will make contributing to the project easier (joyful is preferable).
Onboarding and taking over – Onboarding is huge problem of every 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 and it’s naive to think we can solve it with one tool. But also, it’s not just to tool we need to onboard people in, it’s the workflow as well. The tool we chose and the way we use it should be intuitive enough not to stand on our way to contribute and not to make project depended on a specific person. Most of this could be solved with a detailed documentation on the workflow itself.
There could be more, leave your thoughts in comments.
What are we deciding here?
We are not trying to decide on one tool over the other. We are trying to discuss all the tools we already use, how they solve our problems and how they help our workflow.
Most importantly, we want to figure out the way for reporting and discussing Docs issues. Preferably, we would come up with a unique way for all docs projects but given the differences between projects, it wouldn’t be considered as a failure if we don’t.
However, it is important that we come up with a way to report and discuss issues for each project. Results of this discussion will end up in our Handbook as a reference for contributing to Documentation team.
After around close to 2 years of development, through a total of 3 different teams, we have released the Theme Developer handbook, thereby completing the Developer Hub’s goal of having proper developer docs for the main aspects of WordPress.
The list of people involved (not yet complete) is documented here and last count puts us at close to 100 people involved in the handbook in one way or another.
The handbook has been released in it’s version 1 form and is updated all the way to 4.7.
There’s always more to do and the team continues to manage and improve the handbook on Trello.
Please do give us feedback using the methods detailed here.
We hope this helps everyone make better themes!
Get cracking at https://developer.wordpress.org/themes/
