Agenda for Docs Team Meeting December 07, 2020

The next meeting is scheduled with the following details:

When: Monday, December 07, 2020, 15:00 UTC
Where: #docs channel on 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/..

Meeting Agenda

  1. Project Updates
  2. New Member Mentoring
  3. Monthly Coffee Break
  4. New Meeting Times and Holiday Planning for Docs Team
  5. Google Season of Docs 2020
  6. Clarification about the use of GPLGPL GPL 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. by WordPress plugins and themes
  7. Open Floor

Gutenberg developer documentation – Meeting Notes December 2nd

Attendance: @paaljoachim, @collinsmbaka, @justinahinon.

Agenda: https://make.wordpress.org/docs/2020/11/30/gutenberg-developer-documentation-zoom-meeting-agenda/

Video recording: https://drive.google.com/file/d/1y4PUVjx28AfYH9d75zH_dAyNAt-XYmgo/view?usp=sharing

Summary

In short, we discussed the genesis of the project to restructure the 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’s developer documentation. Then we went through the current structure of the documentation, the different issues that have already been opened and the site that @paaljoachim created to iterate our efforts.

We finally discussed the next steps for the project.

Next steps

Keeping track of all the documentation improvement work

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/ issues related to documentation improvement will be tracked on this project board on the GitHub 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/ repository. These issues will be labeled developer-docs so that they can be found easily.

Gathering information on how the documentation is generated

An indispensable thing to do too is to know and retrieve information on how, when and how often the documentation on the site is generated.

Improve the site “landing page”

The first page you come across when going to the block editor’s developer documentation site is “Project Overview”. As its name suggests, this page is supposed to give developers a general overview of the project, its main parts and allow them to quickly start developing for Gutenberg.

Some issues have already been created for this on the GitHub repository. You can give your feedbacks to them or create new ones if needed.

New structure (summary) for the documentation

This step is highly correlated with the previous one. The documentation should be structured in such a way that it is easily accessible and also has a certain logical order.

For this step, it is important to keep an eye on the different documentation use cases that were identified earlier.

#developer-documentation

New Meeting Time & Holiday Planning

Hello all,

We have the results of the doodle we did to find a better meeting timing – 14:00 UTC.

We are aiming to start the new meeting timing in the new year.

The Documentation Team is also looking to take a break for the holidays. The last meeting for 2020 will be on 14 December. We’ll then start fresh 11 January 2021.

If you have any worries or thoughts, please feel free to comment!

External Linking Policy – 1st review of Plugin Developer Handbook

As the title suggests, this is a first review, using the Plugin Handbook as the testing documentation. We will conduct this initial process to work out the External Linking Policy, which is currently still in “betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process.” phase. Over time, the policy will evolve and take shape as we better understand what it should cover.

The Goal

The goal of this first review has several points:

  1. Classify all external links found in the Handbook;
  2. Define “undoubtedly allowed” links;
    • Propose a list of “undoubtedly allowed” links;
  3. Define “pre-allowed” links;
    • Propose a list of possibly “pre-allowed” authors and websites;
  4. Propose phases of the acceptance process and draft their definitions;
  5. Start discussion about pre-allowed list and acceptance process phases;
  6. Draft a timeline of actions for next steps;
  7. Select at least 3 Docs team members who will act as “official reviewers” for this first review.

All external links found in the 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 Handbook can be found in Docs team’s Google Drive document (with occasional comments from the first review performed by myself): https://docs.google.com/spreadsheets/d/1GhFv8p9veimVM3jMhhazttJLunRjcW7pg0-WO5E0NRk/edit?usp=sharing

1. Classify all external links found in the Handbook

While performing my first review, I classified all resources into “Personal authors” and “Non-personal domains”. This is a very rough classification based on one single difference. 

A person can publish content on different websites and therefore can come out as authors on different resources of which some may meet our policy and some may not (e.g. promo article for a plugin/theme/service). On the other hand, if said person’s content, published on 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/, gets accepted, it doesn’t mean we will accept all resources hosted at github.com.

Non-personal domains with a single author represent one set of rules/values/niche etc and therefore come out as a singular resource that won’t publish content at different domains. Non-personal domains with multiple authors, such as GitHub, YouTube, npmjs etc, can not be seen in this case as a single resource but rather as a tool where different persons publish their content. Seeing GitHub as a singular resource would make sense only if we would consider for example their official blog.

2. Define “undoubtedly allowed” links

What does “undoubtedly allowed” mean?

“Undoubtedly allowed” refers to official or authoritative resources for their respective topics. They go in depth with their topics, and we can expect them to be the most up-to-date resource on that topic. Examples include php.net, gnu.org

2a Define links that can stay and be “undoubtedly allowed”.

Out of all links found in Plugins Handbook, this is my proposed list for “undoubtedly allowed” domains: 

Please note that this list is made up of links actually found in the Plugins Handbook; we don’t need suggestions for random sites not currently in the docs. Please feel free to post your own list in the comments below, once you make sure that your proposed addition actually exists in the Plugin Handbook (provide a link please).

3. What does “pre-allowed” mean?

“Pre-allowed” means that we know this person or website has been giving sound advice and has been nurturing WordPress’s values and principles in the past. Therefore, we have a reason to believe this practice will continue in the future. It does NOT mean that this content will be exempt from review for its relevance and up to date information. 

Links in this classification will not go through the whole “acceptance process,” but rather a content check: 

  • Is it relevant for the part of documentation where it is proposed?
  • Is the information up to date?
  • Is the content in whole meeting External Linking Policy requirements (e.g. not recommending specific plugins/themes/services)?

3a. Propose a list of possibly pre-allowed authors and websites.

Please go through the list in this document and post your “pre-allowed” proposal in comments below. If you feel you should explain your choice, please do. 

This will help us understand values and holes people see in WordPress Documentation and will be a huge starting advantage once we move into the next phases of this policy.

4. Propose phases of the acceptance process and draft their definitions.

In the aforementioned document I have created a “Status (Acceptance phase)” column to indicate the phase in which each link is currently classified. The list of phases will directly affect the whole review workflow so it is reasonable to expect this to change and the workflow to be refined in the future.

Some phases we can be sure to keep all the way, obviously. Such as:

  • Reviewing
  • Accepted
  • Rejected

However, “Reviewing” is rather broad and vague. This phase could be expanded further to, perhaps:

  • Reviewing – Relevance
  • Reviewing – Updated info
  • Reviewing – Advertisement
  • Reviewing – Free access (no paywalls etc)
  • Reviewing – Website/webpage (upholding WordPress values etc)

Broken into smaller phases, the Review phase can be performed easier while the whole process gains clarity and transparency.

If you have any suggestions for phases of the acceptance process, please post them in comments below.

5. Start discussion about pre-allowed list and acceptance process phases.

Hopefully, the comments section will be sufficient for a constructive and productive discussion. If not, we can organise another conference call meeting and clarify all that is indistinct and vague. 

6. Draft a timeline of actions for next steps.

The ultimate goal for Plugin Handbook, as the guinea pig for this process, is to clean up all existing external links, remove invalid ones and (if necessary) restore any valid ones (both, personal and non-personal). 

During this process, we hope to define a pretty solid policy that works in the best interest of Documentation consumers.

To draft a timeline of actions for documentation where we already have external links, first we need the actions defined. While working on this initiative and thinking about possible scenarios, personally I can identify few steps:

  1. Define and apply “undoubtedly allowed” links. Document the process along the way.
  2. Define and apply “pre-allowed” personal and non-personal resources. Document the process along the way.
  3. Review the rest of the links, remove unfitted and keep fitted ones. Document the process along the way.

It’s hard to estimate a process that we have never done before (even the ones we have) but we do need some time frame to make sure this project doesn’t end up unfinished. 

By rough estimation, I’d say that this process could last 6 months in total. First step should be the shortest: ~ 1 month, the last one looks like the longest so I’d give it 3 months which leaves us with 2 months for the second one. As we have already stepped into the first one, the timeline could then look like this:

  1. “Undoubtedly allowed” phase finished by the end of 2020.
  2. “Pre-allowed” phase finished by the end of February 2021.
  3. “The rest” phase finished by the end of May 2021.

If we completed everything within this timeline, WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Europe Contributor DayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. could be a good moment to start work on other parts of Documentation.

7. Select at least 3 Docs team members who will act as “official reviewers” for this first review.

These 3 Docs team members will be noted as a committee who approved “undoubtedly allowed” links. Of course, the more people conduct review and share feedback – the better, but we need defined names responsible for allowing/rejecting resources to make sure reviews will be conducted in full and taken seriously.

Obviously, I already did the first review, so I need two more volunteers who are members of the team and familiar with this whole initiative.

If you are interested, please post it in the comments below.

#external-linking-policy

Agenda for Docs Team Meeting November 30, 2020

The next meeting is scheduled with the following details:

When: Monday, November 30, 2020, 15:00 UTC

Where: #docs channel on Slack.

Meeting Agenda

  1. Project Updates
  2. New Member Mentoring
  3. Monthly Coffee Break
  4. Meeting Times
  5. 2020 Holiday Planning for Docs Team
  6. Google Season of Docs 2020
  7. Discussion: Structure of the Handbooks using flow chart
  8. Open Floor

#agenda, #meetings

Gutenberg developer documentation – Zoom meeting agenda

In a previous post, we shared a Doodle link to choose times to attend a Zoom meeting on 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/ developer documentation.

The selected date for the meeting is:

Wednesday, December 02, 2020, 08:00 UTC

Zoom link: https://us04web.zoom.us/j/79656401480?pwd=cXZ1U2t2MjFYQUFrQ3EwMzRLYW93UT09

Topic: WordPress Documentation Team - Gutenberg Developer Documentation

Join Zoom meeting:
https://us04web.zoom.us/j/79656401480?pwd=cXZ1U2t2MjFYQUFrQ3EwMzRLYW93UT09

Meeting ID : 796 5640 1480
Passcode : 9xHGhA

If you want to participate in the meeting, please read the initial restructuring proposal and the follow up post if you need more context.

Agenda

  • Introduction to the Gutenberg developer documentation restructuring proposal
  • Review of the current structure of the documentation (@paaljoachim)
  • Review of documentation use cases
  • Discussion on adjustments to be made to the documentation and next steps to move the project forward
  • Open floor

If you have others items that you would like to be discussed at the meeting, please comment on them in this post.

#block-editor, #developer-documentation

Docs Team Coffee Break November Summary!

The October Coffee Break took place on the 19th instant with at 10 AM UTC timing which saw the presence of 5 contributors from the Global Documentation Team. Kudos to @estelaris for hosting!

Docs Team Coffee Break for November 2020

We talked about our professional life and where are we located. There were a few hypothetical questions that was asked which brought an instant smile to all of our faces.

Answering questions about our lives

I had the pleasure to put my online photography skills to test that I acquired through volunteering for WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Europe online 2020 by capturing a few virtual selfies with permission from the participants. Thanks to @estelaris, @chaion07, @sukafia, @tacitonic & @kafleg for joining us.

The details and other information regarding the Coffee Break for December will be discussed during the Weekly Meeting for 30 November 2020. If you are interested to host the next coffee break then please let us know.

Thank you!

#coffee-break

Summary for Docs Team Meeting on 23 November 2020

Attendance

@estelaris, @chaion07, @bph, @harishanker, @tacitonic, @veralee, @justinahinon, @paaljoachim, @cguntur

Thanks to @estelaris for facilitating the meeting.

Housekeeping
Project Updates

@bph is planning to do a guided documentation sprint for the BEE-Docs starting this Wednesday through Friday (25 to 28 November). The extensive list of the changes in WordPress 5.6 that needs to be triaged and categorized, compared to the current pages and transformed into a contributor task list. Birgit will be online every morning 9 to noon EST. Please join her at your convenience during these times and contribute to BEE-Docs. Birgit will be posting an announcement p2 later on.

@justinahinon is collaborating with @paaljoachim for 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/ Developer Documentation in order to improve it. Justin hinted that there might be a bit more progress than the past weeks.

New Member Mentoring

6 new members joined #docs in the week between 16 and 23 November 2020. Thanks to @prubhtej for the information.

Meeting Times

Due to the general confusion with the time-zones a new Doodle was created by @kenshino. Everyone is requested to cast their votes.

Monthly Coffee Break

The November Coffee Break was hosted by @estelaris with 5 participants joining. @chaion07 will be posting a summary in a p2 later on.

Google Season of Docs 2020

@tacitonic is reported the following:

@estelaris mentioned that the classification project will start reviewing the 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. articles and coordinate with the BEE-docs team to figure out how to move forward.

The GSoD team would love to hear from the Docs team on the Do’s and Dont’s including comments related to the Style and Tone section.

Open Floor

@bph informed everyone that we need to enable discussion per page since the feedback section that’s now available on HelpHub. Users will be able to leave comments for the Admins and Moderators to be able to view them using wp-admin. Also in the works is a way to revise an article without taking the existing page offline or update unfinished. We will be able to work on revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. and then schedule making them public.

@paaljoachim asked if there been any talk about going through the structure of the handbooks and suggested that creating a flow chart of how docs are linked together can help improve on the user experience. @estelaris mentioned that there has been discussion on this in the past and advised everyone that any idea or a proposal on the topic is welcome. Paal will be bringing this topic next week since majority of the team is unavailable for this meeting.

#meeting-notes, #meetings, #summary

Gutenberg developer documentation – Doodle for a meeting

This post proposes a meeting to go through the current structure of 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/ developer documentation and discuss its information architecture.


A few months ago, I made a proposal to restructure the Gutenberg developer documentation. With the #core-js team, we then worked to identify the use cases of this documentation.

But there are still some points in relation to this documentation and the proposal that need to be clarified. It would be interesting to discuss this in a video meeting with interested people.

Here is the a Doodle link to choose the slots that suit your schedule for next week to participate in the meeting: https://doodle.com/poll/f4zpukgkhit92vdi.

Please read the initial restructuring proposal and the follow up post if you need more context.

The detailed agenda for the meeting is coming soon.

#block-editor, #developer-documentation

Block Editor Documentation Sprint for HelpHub Nov 25 – 27.

The 🐝 – docs (Block Editor End user) team will hold a “Documentation Sprint” on Wednesday, November 25 through Friday, November 27, 2020. There will be permanent presence in the #meta-helphub channel from 9 am – noon EST as well as Zoom office hours (see schedule below).

Dedicating a focused time slot on each of the three days, should give us enough momentum to check in with existing contributors and onboard new contributors. We also should get a head start on updating the documentation to WordPress 5.6 and close some gaps that we still have in our End-User documentation.

Kick-off is on Wednesday 25th at 9am EST in #meta-helphub.  We will begin with a discussion and the preparation of a Google Sheets docs task list from this raw list of relevant updates: one for new contributors, one for experienced contributors.

Updates will be published in the #meta-helphub channel on 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/..

Once the lists are prepared, contributors can sign-up for tasks, and if they are not yet familiar with our processes we will be there to help them get started.

If you are an experienced contributor and already have existing commitments via the 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. board, we hope you can dedicate some time to finish your assignment or let us know about your blockers, so we can assist you.

Please take the opportunity to test the blocks and features with the WordPress 5.6 RCRelease Candidate A beta version of software with the potential to be a final product, which is ready to release unless significant bugs emerge. via the WordPress Beta Tester plugin, and include relevant changes and screenshots of the new version.

Zoom office hours schedule

Contributors will be holding office hours on Zoom for questions, reviews and discussion. Sometimes it is much easier to discuss something face-to-face or if demos are needed.

  • Wednesday, Nov. 25, 2020
    • 10 am EST (15:00 UTC) – 10:50 EST (15:50 UTC)
    • 11 am EST (16:00 UTC) – 11:50 EST (16:00 UTC)
  • Thursday, Nov. 26, 2020
    • 10 am EST (15:00 UTC) – 10:50 EST (15:50 UTC)
    • 11 am EST (16:00 UTC) – 11:50 EST (16:00 UTC)
  • Friday, Nov. 27, 2020
    • 10 am EST (15:00 UTC) – 10:50 EST (15:50 UTC)
    • 11 am EST (16:00 UTC) – 11:50 EST (16:00 UTC)

Other Timezones

Outside those times, we are answering questions and have discussions in the #meta-helbhub Slack channel.

If contributors in other times zones are available to be present in #meta-helphub channel or on Zoom on these three days, please comment on the post here with the time windows. It would be great if we can cover more time zones.

How to get in contact

Please comment on this post if you are able to dedicate some time during the next three days and join us on this 🐝- – docs catch-up sprint.

  • Comment with your questions, ideas and commitments below,
  • Join me (Birgit Pauli-Haack) at the first office hour Wednesday 10 am EST – 15:00 UTC on Zoom (link will be posted in the #meta-helphub channel or
  • PingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me on WP Slack #meta-helphub.

CU Y’all there!

Thank you to @tacitonic and Laura Byrne for their review for clarity and grammar.