Below is a list of projects presented by WordPress for Google Season of Docs 2021. Prospective technical writers can also suggest new project ideas in the comments section.
People involved:
- Organization administrator: Justin Ahinon @justinahinon
- Backup organization administrator: Atharva Dhekne @tacitonic
- Mentors:
Project list
Project name: Create a system to track updates and suggestions to the WordPress documentation
Project description
The problem: The WordPress documentation is huge and divided into multiple sections. There is user documentation and developer documentation of different projects (themes, plugins, block Block 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, APIs, etc.).
All this documentation is subject to frequent changes as the projects to which they belong evolve. So we end up with requests for changes, requests for updates that are frequently reported on various channels: Slack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/., Meta Meta 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. Trac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/., GitHub GitHub 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/, etc.
The fact that we don’t have a unified system for change requests and documentation updates makes collaboration difficult; and can be an obstacle for new contributors who want to start with documentation contribution.
So, WordPress really needs 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.
Measuring the project’s success
The main indicator of success is the effective implementation of a system and process to report documentation that is obsolete, needs to be updated or corrected.
The second indicator of success is the use by contributors of the system and process implemented.
Required skills
The technical writer who will work on this project should have an idea of WordPress documentation, how they work, and how the documentation team maintains them.
The technical writer will have a mentor with experience on the documentation team, who can provide assistance and guidance as needed.
Project name: Documentation for a better on-boarding experience: Supporting new contributors to WordPress
Project description
The problem: Reported by W3Techs WordPress currently powers over 40% of the web. The WordPress Org comprises of contributors and the number is growing by the day. With 18 Make WordPress Teams it can be a daunting experience for new contributors in finding their place. Many teams have their on-boarding documentations as part of the Handbook. Some are automated, for example the core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. team while others lack enough clarity for new contributors to understand.
Thus, WordPress should include both technical and other know-how documentation for contributors. Season of Docs is the perfect excuse to improve each of the 18 teams’ handbooks emphasizing on the contributor on-boarding experience.
This project aims to improve the documentation of the on-boarding experience for contributors. With rich, interactive content including multilingual videos, the goal is to support the existing documentation from individual team’s handbooks and to standardize them in a way that can be truly beneficial for the contributors.
Measuring the project’s success
Adding relevant section to the handbooks and those pages would be the main success criteria for the project. Being able to include localized content can also help improve the overall user experience and reach a wider audience.
An additional success criteria for the project can also be on the use of the content and in the implementation of the content when put to the test.
Required skills
The technical writer should have an understanding on the following:
- How Make WordPress Teams function
- Weekly Meetings and Triage Sessions
- Workflow of the Make WordPress Teams
- How to propose changes for the Handbook
- How WordPress is being improved (release process)
- Where to ask for help and how to avail them
- Identifying the contact person for each Make WordPress Teams
The technical writer can have a mentor with experience on the documentation team, who can provide assistance and guidance if needed.
Related Material
Project name: Write Gutenberg The 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/ block editor end-user documentation
Description
There are gaps in the existing documentation for the Gutenberg block editor 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 UI UI 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, Gutenberg block editor documentation is evolving rapidly with new version releases.
Required skills
A content creator’s (blogger, writer) understanding for the block editor; no development skills are required.
Related material
Project name: Improve existing user and developer documentation and handbooks
Description
We have a lot of developer documentation. WP Core’s documentation is mostly automated. However handbooks that describe how one would create a theme, make a plugin A 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 API The 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 CLI Command 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 release 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.
Another improvement would be to adopt the newly published WordPress Documentation Style Guide for existing documentation.
Related material
Project five: @mkaz
Project Name: Extending block editor developer documentation
Description
Documentation on developing on top of block editor is, depending on the topic, either scarce, outdated, or non-existent. Considering that the block editor is a significant language leap for WordPress developers, 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.
Related material
- Link to the open source Open 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://developer.wordpress.org/block-editor/
- Updates to an existing documentation set – https://developer.wordpress.org/block-editor/tutorials/
- 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 hooks In 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.
- Link to similar documentation in other projects – https://www.gatsbyjs.org/tutorial/
Additional information
- Previous participation in Season of Docs, Google Summer of Code or others:
WordPress participated in Google Season of Docs 2020. WordPress was also a mentoring organization for Google Summer of Code 2014.
#season-of-docs-2021