Jon (Kenshino) 1:18 pm on October 14, 2019  

Changing the nature of our weekly meetings

So HelpHub has already been deployed and other projects are in need of some focus.

I’ve been thinking about how to make our meetings more useful. Meetings that are just about updates aren’t the best use of everyone’s volunteer time.

Meetings that require involvement but no one is prepared for ain’t the best either.

So I’m hoping that we can improve how we run the meetings. I’d love for everyone to suggest something.

I’ll start off –

  1. Let’s rotate facilitators and note takers. Both roles have the ability to help someone really get into the groove and understand the Docs Team.
  2. Let’s change all meetings to Docs Team meeting (no special HelpHub dedicated only meetings)
  3. Let’s time-box each section of the meeting
  4. Let’s have focuses for each meeting. (e.g.)
    • Docs Team Meeting (60% time on HelpHub discussions, 40% other pieces)
    • Docs Team Meeting (60% time Docs Handbook, 40% other pieces)
    • Docs Team Meeting (60% DevHub discussions, 40% other pieces)
    • Docs Team Meeting (60% Flagship WordCamp contributor day discussions, 40% other pieces)
    • You get the drift!

Any better ideas? I’d love to hear them!

Sunday Ukafia 2:22 pm on March 29, 2020
Tags: ,   

Agenda for Docs Team Meeting 30th March 2020

Our next Documentation Team meeting is scheduled for Monday, March 30, 2020, 15:00 UTC

in the #docs channel on Slack.

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Project Updates
  4. Handbook revamp
    • Homepage update
    • Deadline for next 2 or 3 pages
  5. Categorization Project, Alterations Workflow (discussion)
  6. Open Floor

#agenda, #meetings

Sunday Ukafia 6:50 pm on March 23, 2020
Tags: ,   

Summary for Docs Team Meeting 23rd March 2020

Attendance

Facilitator: @estelaris
Notetaker: @sukafia

@estelaris, @kenshino, @leogermani, @WPZA, @bph, @nao, @atachibana, @estelaris, @tomf, @pbrocks @sukafia, @nobnob, @audrasjb @zzap, @netpassprodsr, @FahimMurshed, @marcio-zebedeu, @joyously, @ibdz

Facilitator next week: @sukafia
Next meeting will hold on:

Monday, March 16, 2020, 15:00 UTC

Project updates

@bph updated the WordPress editor article and hopes to do two/three of the missing pages a week on the end-user documentation for the block editor.

@atachibana re-routed Codex Function pages to Code Reference. Completed 39% (417 of 1069).

@estelaris commended @bph for the update on the WordPress editor and asked if there were still missing articles for the block editor, which @bph responded that a few pages were missing among the embed blocks and the new blocks in 5.3 and 5.4. and some are in dire need to updates as the UI changed a bit, but that’s a bit of an uphill battle as they UI will change again in August.

@bph shared the Trello board for Gutenberg end-user documentation. – https://trello.com/b/JnTCzOsL/gutenberg-end-user-docs

@Marcio-zebedeu offered to help in Migrating Code Reference. @estelaris prompted everyone who’s volunteering to help someone to please specify the project/task so we can properly record it in our notes.

Handbook revamps

@estelaris made it known that @leogermani wasn’t available in the meeting due to meeting conflicts but that he will consolidate the changes to our welcome box later in the day and publish it.

Categorization project

On the categorization project, @estelaris said we “must find high-level goals and create user stories to exemplify our goals and to give better direction to those that would like to help and are outside the docs team” She shared a link to the spreadsheet for the project – https://docs.google.com/spreadsheets/d/1_Ea2yeF5Rfy_YDk7pBRJ4rdljhMjygXFqBq8gWwhbaE/edit#gid=1762929540

@estelaris briefed the team that “there are exactly 172 articles that we need to reclassify and that a group of contributors at WordCamp Vienna had helped to create categories and subcategories that could help but that they’re still far from finishing the project. She added that the new categories/subcategories are on the “Category Recs tab”.

Several deliberations were made on this. It was agreed that articles shouldn’t be repeated, tags were suggested as a way to co-relate articles.

The conclusion was to decide on goals and come up with user stories next time.

Open floor

@netpassprodsr volunteered to contribute to Re-routing of Codex Function pages to Code Reference.

@sukafia shared a draft of the “Extending WordPress” article which he had suggested to be included in the documentation in the previous meeting. He’s to work on it alongside @tomf for inclusion in the Overview of WordPress article.
https://docs.google.com/document/d/11fPqjpFNDQt0WKtnTkk_VAnUMYMndoEd9ppGZf1mcBw/edit

Transcript of the meeting:
https://wordpress.slack.com/archives/C02RP4WU5/p1584975640002300

#meetings, #summary

estelaris 4:00 pm on March 22, 2020
Tags:   

Agenda for Docs Team Meeting 23rd March 2020

Our next Documentation Team meeting is scheduled on Monday, March 23, 2020, 04:00 PM GMT+1

in the #docs channel on Slack.

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Project Updates
  4. Handbook revamp
    • Welcome Box update
    • Homepage update
    • Deadline for next 2 or 3 pages
  5. Categorization Project, Alterations Workflow (discussion)
    • Finding high-level goals
    • Creating user stories
  6. Open Floor

#agenda

Milana Cap 4:02 pm on March 20, 2020
Tags: ,   

X-post: Updating the Coding standards for modern PHP

X-comment from +make.wordpress.org/core: Comment on Updating the Coding standards for modern PHP

Milana Cap 9:05 am on March 20, 2020
Tags: ,   

X-post: Associating GitHub accounts with WordPress.org profiles

X-comment from +make.wordpress.org/core: Comment on Associating GitHub accounts with WordPress.org profiles

Milana Cap 4:32 pm on March 16, 2020  

Summary for Documentation Team Meeting 16 March, 2020

Attendance

@softservenet, @kenshino, @milana_cap, @pbrocks, @ataurr, @felipeloureirosantos, @pmbaldha, @atachibana, @kartiks16, @passoniate, @tjnowell, @marcio-zebedeu, @estelaris, @deadpool76, @sukafia, @cristianozanca, @leogermani

Notetaker: @milana_cap

Facilitator next week: @estelaris

Next meeting will happen on

Monday, March 23, 2020, 15:00 UTC

Project Updates

Codex rerouting for Functions are were done 410 of 1069 (38.4%). Almost all credits in this week are @stevenlinx.

Handbook Revamp

@leogermani started document for reviewing Handbook: https://docs.google.com/document/d/1X6MiAD7qpdEEMAfFE2pM_hFAynlPg0g5aOSa1em05O8/edit?usp=sharing

Everyone is welcome to review Handbook and leave feedback in document. Especially people new to the team. If Handbook makes no sense for them then we need to improve it. If you read handbook and have no idea what is project about or how to contribute to it, it means the handbook is poorly covering the project. Anyone should be able to start contributing after reading it.

First tasks are Welcome message, which is really outdated, and Handbook home page (as Welcome message links to it). Deadline for this is 7 days from today. @leogermani will gather all the feedback.

New value/motto to the Docs team – Better now than perfect tomorrow.

Leave feedback in the document, please.

Outliers in Codex

Specifically talking about Codex pages which are neither Theme, Plugin or API specifics, e.g. https://codex.wordpress.org/Converting_Database_Character_Sets

Plan is to first identify these pages on a list so that we can describe what they are doing as a group and figure out where to put them.

Suggestions are that we just create “Misc Handbook” and move pages there as we discover them or to make a list of all pages first.

We’ll postpone this decision until the time we have 10 such pages identified. Someone should take ownership of this and we will discuss it on next meeting.

Policy for External Linking

There is an ongoing discussion about this: https://make.wordpress.org/docs/2020/03/16/external-linking-in-docs-policy/

Everyone is welcome to participate in discussion.

Documentation License

There is an ongoing discussion about this: https://make.wordpress.org/docs/2020/03/16/documentation-license/

Everyone is welcome to participate in discussion.

Categorization Project, Alterations Workflow

HelpHub article can be found in several categories, but @estelaris‘ research has proven that this is very bad for usability. Essentially we’re categorising poorly and therefore there is such a need to categorise them multiple times.

Here is the document to illustrate this research: https://docs.google.com/spreadsheets/d/1lNxlyouZ9N6NuwA21lld3t_TZ6T–TVQGzB8fdjBl-M/edit?usp=sharing

The classification we have has been inherited from Codex and it is a classification from 15 years ago. It may have worked at some point but as we add new articles, it makes no sense any more.

However, we cannot disrupt the structure as we have millions of users that are familiar with the structure but we can make smaller changes to adapt and make it easier to search for users and even for Google.

Here is the post to explain the project: https://make.wordpress.org/docs/2020/02/21/findings-in-the-reclassification-of-wordpress-org-documentation/

We need to set real goals and clear tasks/workflows for this project. Document for following process: https://docs.google.com/spreadsheets/d/1_Ea2yeF5Rfy_YDk7pBRJ4rdljhMjygXFqBq8gWwhbaE/edit?usp=sharing

First we are going to define “Discoverability” and set few user stories. A dedicated meeting will be held for this. @milana_cap volunteered to help @estelaris with this.

Open Floor

@sukafia proposed adding HelpHub category or article on extending WordPress. What it is and what it can be used for. It is suggested that @sukafia review HelpHub article where this info could fit and add suggestions for edit. @softservenet volunteered to help.

Transcript of the meeting: https://wordpress.slack.com/archives/C02RP4WU5/p1584370804344000

Milana Cap 11:02 am on March 16, 2020  

External Linking in Docs Policy

Documentation at WordPress.org has a large number of external links mostly added to Codex and then copied to all other/new parts of docs. We have to decide on policy for external linking. Do we allow it and, if so, what is the criteria?

Even though external linking, as an idea, should be used for more in-depth explanation of the subject, things to consider:

  • External links need to be reviewed by our team members which is more work but more importantly, could cause our members unwanted situations when link is rejected
  • External links tend to be outdated (sooner than we expect)
  • We have no control if content on external link gets changed after approval, regular checking is highly undesirable another task for docs team
  • External links have been (and will be) used for gaining traffic and/or marketing own services
  • There’s probably more

We have to decide “yes” or “no” for external linking. Let’s keep in mind that documentation should be self sustained; our team members are not responsible for the content outside of WordPress.org but are responsible for the content inside of it.

Please leave your thoughts, as well as pros and cons in comments. Thank you.

Milana Cap 9:54 am on March 16, 2020  

Documentation License

There’s been a discussion lately about licensing all the documentation on wordpress.org. The task is to decide under which license we are publishing documentation.

Codex is under GPL v2 and a large part of out current documentation is copied from there. However, since then new Handbooks have been written on wordpress.org: CLI is under MIT while REST API still has no license but its rep, @kadamwhite, is comfortable with GPL.

As GPL is more appropriate license for code we are considering multi-license for documentation. We definitely want to keep GPL in case we need to embed it in WordPress (software), as recommended by @matt. Another license could be more appropriate for documentation; e.g. GFDL or CC0 (under which is Stack Overflow).

While deciding on this matter, we have to answer these questions:

  • How is WordPress documentation used and how it can be used?
  • What are forms of docs distribution?
  • What are freedoms we want to ensure for docs users?
  • What are restrictions, if any, we want to pose on docs users?
  • Did I miss anything?

Please feel free to post your thoughts/questions in comments below. We need as many people involved as possible. Thank you.

Tom Ford 8:11 pm on March 14, 2020
Tags:   

Agenda for Docs Team Meeting 16 March 2020

Our next Documentation Team meeting is scheduled on: Monday, March 16, 2020, 15:00 UTC in the #docs channel on Slack.

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Project Updates
  4. Handbook Revamp (outdated items)
  5. Outliers in Codex (non-theme or plugin)
  6. Policy for External Linking (continued discussion)
  7. Licensing (continued discussion)
  8. Categorization Project, Alterations Workflow (discussion)
  9. Open Floor
Prashant Baldha 10:55 pm on March 11, 2020
Tags: Documentation License, external linking,   

Summary for Docs Team Meeting: 09 March Meeting

The agenda for this meeting is on the https://make.wordpress.org/docs/2020/03/09/agenda-for-docs-team-meeting-9-march-2020/.

Attendance

@Kenshino (Jon), @cristiano.zanca, @milana_cap, @atachibana, @pmbaldha, @tomf, @bph, @leogermani, @nullbyte, @themiked, @johnbillion, @felipeelia, @chetan200891, @yui, @pbrocks

Documentation License for HelpHub, DevHub

@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 GPL. 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 API handbook, but The CLI handbook is licensed under the MIT.

@Kenshino (Jon) strongly recommends each representative for projects in Docs to chime in Theme Handbook, Plugin Handbook, WP-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.

Project Updates 

@milana_cap had written the documentation team profile badge page https://make.wordpress.org/docs/handbook/get-involved/documentation-team-profile-badge/.

As per the @themiked, @garrett-eclipse had given some updates for the privacy bits for the plugin handbook but no changes made until now.

Moreover, @themiked has said that the wpdb documentation page is done but the PR to update the inline docs in code (https://core.trac.wordpress.org/ticket/49477) isn’t done yet.

@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 hooks 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 ping 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.org team members (no companies) in that specific topic.

@bph said that WP docs should be self-contained.

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 P2 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):

  1. Any documentation project member should be able to ask the project rep for review
  2. Any project rep change (not #1 but their own change) – some other project rep or @Kenshino (Jon) can be the second pair of eyes
  3. Tiny grammatical / screenshot changes need not go through this approval process

The workflow will be tracked by appropriate and transparent communications in #docs.

Open Floor

All project representatives should read the Badge policy that @milana_cap wrote on the https://make.wordpress.org/docs/handbook/get-involved/documentation-team-profile-badge/. @Kenshino (Jon) want to get a consensus in the next meeting.

@tomf will facilitate next meeting.

@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 API handbook. It isn’t unique to plugins or themes. The Plugins handbook needs a deeper refactoring.

#documentation-license, #external-linking, #meetings