WordPress Documentation Style Guide – Google Season of Docs 2020 Project Report

Google Season of Docs logo, WordPress logo

Google established the Season of Docs program to improve documentation for open sourceOpen 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. 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.

Quick links:

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 accessibilityAccessibility Accessibility (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, GitHubGitHub 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/, Markdown, PHPPHP PHP (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. http://php.net/manual/en/intro-whatis.php., MySQLMySQL MySQL 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/., HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites./CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site., and JavaScriptJavaScript JavaScript 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 GitGit Git 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.org The 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 MetaMeta 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. 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 GutenbergGutenberg 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/ BlockBlock 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 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 CoreCore Core 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).

Contributions to WordPress in 2020 by @tacitonic
Contributions to WordPress in 2021 by @tacitonic

GitHub repository for the WordPress Documentation Style Guide: https://github.com/WordPress/WordPress-Documentation-Style-Guide

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.

Commits authored by tacitonic: https://github.com/WordPress/WordPress-Documentation-Style-Guide/commits?author=tacitonic

Timeline and deliverables

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

Research and references

While planning as well as designing and writing, I researched existing style guides, dictionaries, and WordPress documentation extensively:

Collaboration

Mentors

Mentor: Milana Cap @milana_cap

Mentor: Felipe Elia @felipeelia

Org admin: Chloé Bringmann @cbringmann

Documentation Team Lead: Jon Ang @kenshino

Weekly meetings

Even before the community bonding phase, I participated in weekly meetings over SlackSlack Slack 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 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.

#atharva-dhekne, #documentation, #google, #google-developers, #google-season-of-docs, #google-season-of-docs-2020, #gsod, #gsod-2020, #style-guide, #tacitonic, #wordpress, #wordpress-documentation-style-guide

Call for mentors for the Google Season of Docs 2021

If you’ve been reading the Make/Docs blog this week, then you already know that WordPress will be applying for the Google Season of Docs 2021.

In order to help the technical writers with the projects they will be choosing, it would be ideal if they were accompanied by one or more mentors who have some experience with WordPress documentation. Although it is not mandatory for this edition of the program, we think it could be very beneficial.

If you would like to learn more about the role of a mentor, please read this guide for program mentors.

If you are interested in being a mentor, please mention it in a comment to this post with Wednesday, March 24, 2021, UTC 11:59.

#season-of-docs-2021

Google Season of Docs 2021 – Project ideas list

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:

Project list

Project one: @justinahinon

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, blockBlock 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: SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/., MetaMeta 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. TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/., GitHubGitHub 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 two: @chaion07

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 coreCore 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 three: @tacitonic

Project name: Write GutenbergGutenberg 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 UIUI 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 four: @tacitonic

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 pluginPlugin 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 APIREST 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 CLICLI 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 sourceOpen 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 hooksHooks 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

Call for projects ideas for the Google Season of Docs 2021

Note: UPDATE: Refer https://make.wordpress.org/docs/2021/03/26/google-season-of-docs-2021-project-ideas-list/ for the final project list for Season of Docs 2021.

Got any ideas for WordPress documentation projects for the Google Season of Docs? Share them with us! Project proposals should be in such a way that they can benefit from the work of the technical writers.

Please share your project ideas by Wednesday, March 24, 2021, UTC 11:59.

#season-of-docs-2021

Recommendations for additional team leads

Hello all

We discussed this lightly in a team meeting 1.5 weeks ago but we did not managed to put this into writing.

I have recommended that @milana_cap and @atachibana become Docs’ Team Co-Leads alongside me. They’ve been doing some great work over the last 2 years and have really stepped up in the the team’s leadership and project management aspects.

If there are no objections, we’ll solidify this decision by 28 29 March 2021 (in our Docs team meeting).

Feel free to reach out to me on #docs or via DM if you have questions!

WordPress is applying to Google Season of Docs 2021

This year, WordPress will again apply for the Season of Docs.

What is the Season of Docs?

The Season of Docs is a Google program. It offers open sourceOpen 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. projects an opportunity to improve their documentation. The program also offers technical writers the opportunity to contribute to these open source projects and improve their technical writing skills.

Previous WordPress participations in the Season of Docs

WordPress participated in the 2020 edition of Season of Docs. Two projects were selected for this edition:

The contributors to these projects have made outstanding efforts to achieve them, and the completion of these projects is already having a positive impact on overall WordPress documentation (read WordPress Documentation Style Guide – Google Season of Docs 2020 Project Report).

Who is involved?

At this stage, I am the only person involved as the WordPress organization administrator.

What do we need right now?

To participate in Season of Docs 2021, we need:

  • Projects: (a post will be published soon on the blog to collect project ideas)
  • Mentors: mentors are not required for the 2021 Season of Docs. However, it is very helpful for technical writers to have someone with experience with WordPress and its documentation to provide assistance when needed
  • A backup organization administrator: the organization administrator manages the organization’s participation in the Season of Docs. The administrator role consists in:
    • Being the liaison between Google and the program participants in the organization.
    • Providing regular updates to Google about the progress of the organization participation.
    • Taking care of all the paperwork related to the organization’s participation in the program.

It is therefore ideal to have a backup administrator who can help the first one, and if necessary, can take the lead in case of unavailability.

I live in Benin, in the UTC+1 time zone. It would be ideal to have a backup administrator who lives in a timezone far from mine (more or less).
If you are interested in being a backup administrator, please let me know in the comments of this post.

Resources

Here are some links to learn more about the Season of Docs:

#season-of-docs-2021

A home and a name for Site Editor Documentation (Full Site Editing Feature)

As you may know, the “Full Site Editing via Gutenberg” is the main goal for 2021. We still don’t know when exactly it will become the part of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. but to avoid missed opportunities (as we had them in the past with GutenbergGutenberg 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/) let’s start preparing documentation space for this new feature’s arrival. 

We want to join efforts with other teams already working on Site Editor. Namely, the Test team has an ongoing Outreach Program (lead by @annezazu), Themes team (mostly @poena) is explaining what this feature is and how it’s working, Core and Design teams are building it: pull requests and issues

Our job is to document it. 

First things first

Before we start with anything else, we need to know two things: the name and the place.  

The name

It’s been called “Full Site Editing” throughout the community but, as history teaches us, this is most likely to stay around only as the code name for the project, used among people working on it. 

We will probably have a different name facing documentation consumers so, to avoid confusions and to have a proper Handbook slug from the beginning, we might want to spend some time on thinking it through. This is not a task only for the Documentation team, of course, and we hope to get input on this post from all teams involved.

It’s been suggested in #docs chat, that “Site Editor” might be an appropriate name (just as Gutenberg became BlockBlock 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) so we’ll use it as a starting point. Please leave your opinions and suggestions in the comments below.  

The home 

The whole user facing documentation is roughly divided into end user documentation (HelpHub) and developer documentation (DevHub). Obviously, Full Site Editing feature should be explained to both, in a way that is useful to each group. 

@bph is already doing an amazing job in organising and creating content for end user Block Editor documentation and she has a plan for Full Site Editing feature.

The problem we are facing is the home for developer part of Full Site Editing feature documentation. It doesn’t fully belong to any existing Handbook as it requires features from different areas (it needs to be enabled in theme but it assumes template post types, it doesn’t create new blocks but it does use blocks specifically created for it, it can use global styles etc).

Majority of the Documentation team agrees that Full Site Editing feature shouldn’t be buried in any one existing Handbook but it should be mentioned where relevant. Also, we agree that the full concept should be explained in one place from and to where we can easily inner link relevant places in other Handbooks. 

Considering there might be much more to Full Site Editing feature in the future and we might need more space for it than, say, one page, the Documentation team propose a new Handbook under DevHub. 

The slug for this Handbook depends on the name we settle with. Also, it would be a good time to decide if we want to have this Handbook built and generated from GitHubGitHub 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/ (like WP-CLIWP-CLI WP-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/, REST APIREST 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/., Block Editor and Coding Standards are) or do we want to publish content directly from WordPress. 

Please leave your feedback in comments below by 25th February. Thank you.

#fse, #site-editor

Docs Team Coffee Break February 2021 Summary

The February Coffee Break took place on the 24th instant at 11 AM UTC timing which saw the presence of 5 contributors from the Global Documentation Team. Kudos to @chaion07 for hosting!

Docs Team Coffee Break for February 2020

I came online at the scheduled time but did not see anyone joining. So I waited and sent a message across my workplace, weDevs which resulted in a few of my colleagues joining instantly.

We mostly talked about how to become a Documentation Contributor and what projects are there to contribute. I tried to answer various questions ranging from the Handbook to the weekly meeting. All contributors were encouraged to attend the weekly meetings.

We thank @atiktonmoy, @thisisyeasin, @reachmazharul & @gtarafdarr for joining the Docs Team Coffee Break for 2021. We invite all of you to join the coffee break for March 2021 as it progresses from planning to execution.

#coffee-break, #meeting-notes, #meetings

🐝-Docs Team Sprint Feb 25, 2021

🐝-docs stands for Block-Editor End User documentation.

What makes Contributor Days at WordCamps such a great event is the concerted focused time and working alongside of each other in person. You meet teammates from around the world, you can get instant answers to questions, help when you get stuck and have short discussions on important issues. It does wonders to motivation, productivity and camaraderie. Just because there aren’t any in-person WordCamps, doesn’t mean we can’t have remote Contributor Days, I call ’em a Team Sprints. It might be the next best thing.

So, dear team members, Contributors, current and future once, you are invited to join us for our next sprint on February 25, 2021. To accommodate different time zones, there will be two 2-hour sessions, starting at

The Team Sprint will be held on Zoom and the URLs will be published on Thursday in #meta-helphub channel an hour before the session. The accompanying chat will also take place in #meta-helphub, so contributors joining us asynchronously can leave comments and questions, too. Follow-ups can then happen in #meta-helphub threads.

Topics

The topics will mostly be determined by the people able to join us, and what we would want to work on the next two hours. These are only suggestions, covering all four projects and more.

  • Onboarding of new contributors
  • Virtual walk through our tools and documents (TrelloTrello Project management system using the concepts of boards and cards to organize tasks in a sane way. This is what the make.wordpress.com/marketing team uses for example: https://trello.com/b/8UGHVBu8/wp-marketing., Make blockBlock 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., Handbook, Google Docs, using a test site etc)
  • Early peak on Scheduling updates to published posts on WordPress.org (demo)
  • Process of updating existing documentation with changes from new versions.
    • 1st iteration for 5.6,
    • 2nd iteration for 5.7.
  • Creating end-user documentation for Full-Site Editing
  • “More Options” project
  • Handling Feedback / Comments

What else do you want to talk about? Leave questions and suggestions in the comments or on #meta-helphub

Hope to see many teammates on Thursday.

PS: Yes, there is also a coffee break scheduled for Thursday. It gives you an opportunity to hang out with the rest of the docs team! It’s way too early for me, though.

Requirements for a new design for the article pages in user documentation

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:

  1. Article voting (#7) vs feedback: contributions from the public (#240)
  2. Search area (#9)
  3. SidebarSidebar A 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)
  4. TOC styling (see #111)
  5. Language (#201) vs localization (#283)
  6. CategoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. terms archive (#231)
  7. Mobile view (#235)
  8. Mobile sidebar (#236)
  9. WP version page (#245)
  10. Add changelog (example)
  11. Index dev notes by release (example)
  12. 404 with link to forum (#47)
  13. Icon for external links (example)
  14. Add breadcrumbs
  15. Change hovering anchor# icon

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)

2. Search area (#9)

Maintain the search area for documentation and forums. Make it prominent for mobile.

3. Sidebar navigation styling (#111)

Follow the new style for pages in WP.org. Use only the main category items on the menu with links to each subcategory TOC pages

4. TOC styling (see #111)

5. Language (#201) vs localization (#283)

Are there Rosetta sites that will not be using the HelpHub pluginPlugin 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 to translate documentation? Is it still necessary to add the language feature? 

6. Category terms archive (#231)

This PR will be resolved with the new classification for the articles that was done via GSoD.

7. Mobile view (#235)

Currently the view on mobile for documentation uses a very large band and it gives the impression that there is nothing else. So increase information above the fold.

8. Mobile sidebar (#236)

The sidebar on the mobile version will be affected with the new navigation. At the moment, it looks like this:

9. WP version page (#245)

There will be a review but will use the same template as the documentation articles.

10. Add changelog (example)

A changelog is essential to keep users informed on what has been changed and when. It is being tested at the time this post was written.

11. Indexed dev notes by release (example)

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. 

12. 404-not-found with link to the forum (#47)

The new design will include a 404 page with a link to the support forums.

13. Icon for external links (example)

In the article template, include an icon to highlight a recommended site or external link. 

14. Add breadcrumbs for navigation

Breadcrumbs will be added to ease navigation

15. Change hovering anchor icon

Nowadays the hashtag # symbol has other connotations as it is common in social media. The link icon is commonly used as a hovering anchor  

This list is by far what the docs team has gathered. The post will be open for discussion and recommendations until 12 February 2021. 

The next posts on this series will be:

Part 2: Documentation: a different classification, navigation and SEO

Part 3: Draft templates for article documentation 

Part 4: Proposal for a new design for documentation 

Props @milana_cap for proofreading and final review.