Summary for Docs Team Meeting: August 24, 2020

Attendance

@atachibana @milana_cap @chaion07 @bph @ibdz @collinsmbaka @crstauf  @themiked @kenshino @tacitonic @softservenet @b-07 @khushbu1983 @kafleg  @timohaver @kulsumsiddique  @manthanadmane @sasiddiqui @dmivelli @felipeloureirosantos @bizanimesh  

Agenda

You can find the Agenda here.

Notetaker: @b-07

Notes Reviewed by: @chaion07

Facilitator: @chaion07

Facilitator for Next Meeting: @justinahino

Follow the meeting on the Slack channel for Docs.

Project Updates

@milana_cap  added patches on this 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. ticket https://meta.trac.wordpress.org/ticket/4915. She also started working on videos on how to set up a local HelpbHub instance.

@bph mentioned that they are making great progress. They created 1 new page on how to move blocks and updated 11 pages to 5.5 status. She also updated the channel with the following information: 

  • New pages needed – 10
  • WordPress 5.5 – 24 
  • WordPress 5.4 – 18
  • WordPress 5.3 – 2
  • WordPress 5.0 – 20 
  • Pre WordPress 5.0 – 2
  • Total 76 pages

@atachibana mentioned that he and @stevenlinxf  migrating and re-routing of the codex to code reference for

  • Classes: 13 of 43 (30.2% <- 14.0%)
  • 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.: 17 of 355 (5.6% <- $4.8%)

External Linking Policy

@milana_cap mentioned that on 25th August there will be a zoom meeting to discuss unclear stuff. More details on that meeting can be found here

New Member Mentor Training

@tacitonic provided new members update: 17 People have joined #docs in the last week. A total of 28 people have joined #docs in the month of August.

Monthly Coffee Break

The August Coffee Break is set for this Thursday (August  27) at 1:00 PM UTC. More details on this here.

Google Season of Docs 2020

@timohaver mentioned that they have GSOD technical writers to move ahead with two projects: a global style guide and improving article discovery.

For the style guide, @tacitonic  is the  GSOD technical writer, @milana_cap and @felipeelia are the mentoring team.

For improving article discovery, @dmivelli is the GSOD technical writer,  @estelaris and @timohaver  are the mentors.

The writers will be in an acclimation phase until middle of September. Then they start 10 weeks of research and writing for their projects.

Open Floor

There was nothing much discussed on the open floor. So @chaion07 ended the meeting with this great quote from Foster C. McClellan:

Trust yourself. Create the kind of self that you will be happy to live with all your life. Make the most of yourself by fanning the tiny, inner sparks of possibility into flames of achievement.

Agenda for Docs Team Meeting August 24, 2020

The next meeting is scheduled with the following details:

When: Monday, August 24, 2020, 15:00 UTC

Where: #docs channel on Slack.

Meeting Agenda

  1. Project Updates
  2. External Linking Policy
  3. Contribute to Docs Videos
  4. New Member Mentoring
  5. Monthly Coffee Break Reminder (August 2020)
  6. Google Season of Docs 2020
  7. Open Floor

Just a quote I want to share with all of you:

Trust yourself. Create the kind of self that you will be happy to live with all your life.

Make the most of yourself by fanning the tiny, inner sparks of possibility into flames of achievement.

Foster C.McClellan

#agenda, #meetings

External Linking Policy – Zoom Meeting Agenda

In previous post about External Linking Policy we invited everyone to participate in Doodle for selecting the time and date for conference call via Zoom. The selected meeting time is tomorrow:

Tuesday, August 25, 2020, 19:00 UTC

Zoom link: https://us02web.zoom.us/j/84003455984?pwd=ZzJnY3hVRU9SYy9mNWpRUk40WEJIdz09

Topic: WordPress Documentation Team - External Linking Policy

Join Zoom Meeting
https://us02web.zoom.us/j/84003455984?pwd=ZzJnY3hVRU9SYy9mNWpRUk40WEJIdz09

Meeting ID: 840 0345 5984
Passcode: 921806
One tap mobile
+16699006833,,84003455984#,,,,,,0#,,921806# US (San Jose)
+19292056099,,84003455984#,,,,,,0#,,921806# US (New York)

Dial by your location
        +1 669 900 6833 US (San Jose)
        +1 929 205 6099 US (New York)
        +1 253 215 8782 US (Tacoma)
        +1 301 715 8592 US (Germantown)
        +1 312 626 6799 US (Chicago)
        +1 346 248 7799 US (Houston)
Meeting ID: 840 0345 5984
Passcode: 921806
Find your local number: https://us02web.zoom.us/u/kbyR5ZUocj

Everyone is invited, even if you didn’t participate in selecting the time. If you can attend, you’re very much welcome to do so.

We are planning to continue discussion started in this document, so please get familiar with it if you are planning to join.

Agenda

  • Brief introduction with goals of this policy.
  • License – This seems like the topic that needs the most clarification.
  • Contributors support – How do we make sure to include support to community contributors, people and companies?
  • Promotion, affiliates, paywals, tracking – Appears we do agree on majority of these items.
  • Open floor.

If you have any suggestions for Agenda items, please add them in comments below.

We are planning to record this meeting for everyone who are unable to attend. Using camera is not required.

Thank you everyone for participating and looking forward to see you in Zoom.

#external-linking-policy

External Linking Policy – Doodle for New Approach Discussion via Zoom

Past few weeks Documentation team has been discussing a new approach to External Linking Policy that has been drafted in this document. It is fundamentally different from previous discussions.

We still have some items to clear out and come to agreement about and we believe that conference video discussion would help us better understand each other and move forward. In order to get as many people as possible attend and join this discussion we set up a Doodle with time slots spreading over next week.

You can vote for time slots that fit in your schedule next week and, hopefully, you’ll join us. We want to hear your opinions on the subject.

This is a call for everyone, not just Documentation team members.

In order to keep discussion constructive and to honor the volunteered time of every participant, please make yourself familiar with forementioned draft. You can, also, leave comments on it.

The Doodle for picking the right date and time is here: https://doodle.com/poll/v8yy7auidw3mm6q2

Looking forward to see you there. Thank you.

#external-linking-policy

Season of Docs 2020 Projects Move Forward

Google recently announced that two of our Season of Docs 2020 projects are moving forward:

  • Documentation Style Guide proposed by Jon Ang (@kenshino)
  • Improving Article Discovery proposed by Estela Rueda (@estelaris)

These were two of nine possible Docs team projects proposed to GSOD technical writers for vetting.

We arrive at this happy moment after four months of ongoing process and collaboration. Considering there were 49 other organizations participating in Google Season of Docs 2020, it’s a credit to our community effort to bring dedicated technical writers to both projects.

Docs team contributor Atharva Dhekne (@tacitonic) is the technical writer for the Documentation Style Guide project. Milana Cap (@milana_cap) and Felipe Elia (@felipeelia) will be the project mentors.

For Improving Article Discovery, we welcome Diana Mivelli (@dmivelli) as the project’s technical writer. Project author Estela Rueda and (author of this post) Tim O’Haver (@timohaver) will be the project mentors.

Near term, the Season of Docs timeline allows for our writers to get acclimated. By middle September, Atharva and Diana will be fully engaged in their documentation work through November.

#season-of-docs

Summary for Docs Team Meeting: August 17, 2020

Attendance

@wpza @tacitonic @sumand @timohaver @milana_cap @b-07 @kulsumsiddique @atachibana @tomf @prubhtej_9 @sukafia @kafleg @kenshino @bizanimesh @bph @tomjn @farhadul Islam @collinsmbaka @ibdz @chalon07 @crstauf @leslie @justinahinon @cguntur @themlked @estelaris @cbringmann

Agenda

You can find the Agenda here.

Notetaker: @kulsumsiddique

Notes Reviewed by: @collinsmbaka and @tacitonic

Facilitator: @tacitonic

Facilitator for Next Meeting: @chaion07

Follow the meeting on the Slack channel for Docs

Project Updates

@atachibana: Joined Class & Hook migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. & rerouting project lead by @leogermani. Classes: 8 of 43 (14.0% <- 4.7%) & 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.: 17 of 355 (4.8% <- 4.5%)

@bph:

Update on docs

  • we are making headway in updating pages to 5.5
  • had a short 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. training todoy in our meeting, and answered a few questions
  • Haven’t consolidated all spreadsheets yet, will do so this week
  • Tried to get PRs from 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/ 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/ repository labeled “UserDocumentation” into the #meta-helphub channel so we can be aware and add them to our trello cards

@justinahinon: Posted the proposal on the team p2 last week for a new better structured Gutenberg developer documentation.

External Linking Policy

@milana_cap saw new comments in the doc but didn’t have any time to answer and include them in the proposal. @kenshino suggested having a zoom call on this. @milana_cap has a concern for hosting the videos for review, @estelaris suggested hosting in G drive

New Member Mentor Training

@tacitonic said that 8 People have joined #docs in the past week and a total of 11 people have joined #docs in the month of August. There were limited response the past week from new members after @tacitonic reached out to them personally.

Monthly Coffee Break

@sukafia have scheduled the next Coffee Break on Aug 27, 2020 01:00 PM Universal Time UTC.

Zoom Link : https://us02web.zoom.us/j/81398073676?pwd=aWE1NmZ1NUxhV2hmWDhRMXZTNnRqZz09

Google Season of Docs 2020

Two people got selected @tacitonic and @diana Mivelli. Two mentors will get allocated at the following projects

  • Improve Article Discoverability in WordPress HelpHub Documentation
  • A Full and Renewed Set of Documentation Style Guide

@timohaver and @diana Mivelli will work on Article Discoverability. @estelaris thinks that both the projects will get merged at some point. As a style guide @estelaris will contribute to article discoverability, so we should be able to all work together in both projects

Open Floor

@tomf raised a query regarding WordCamps are not funding any kind of multi-day events (even digital ones) and no longer funding any swag too.

@wpza proposed to remove the WordPress branding + using your own Dashboard styles. Which is when you go to Users > Edit (single user) > Select a theme, a chance for WP devs to upload their own theme for toolbar colours, branding, etc.

Please feel welcome to suggest 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. in the comments.


#docs, #meeting, #meeting-notes, #notes

Contribute to Docs Videos

During last Docs team meeting it was proposed to create short videos showing various ways of contributing to Documentation team. The proposal was well received so we’re moving on to implementation.

The Idea

The idea is to show how to do tasks which are considered as contribution to Documentation team. Some tasks are easier to explain by simply showing how to do it. By recording the demo we are removing the need for repeating ourselves and even having a person who’s going to do all the repeating as a part of the onboarding process.

These videos can be recorded in several ways:

  • You can announce it publicly and ask for audience or you can record it privately.
  • You can do it alone but, if you wish, you can organise with other members of Documentation team to record it together.
  • You can invite someone who is considering to join the team and guide them through the process or let them watch and ask questions.
  • Possibilities are endless..

Implementation

To make things more consistent here is a set of guidelines:

  • Tool for recording: Zoom (account is needed, free is sufficient)
  • Video should showcase one specific task
  • Video title should be precise in what the video is showing:
    • Don’t: How to contribute to HelpHub
    • Do: Reporting an error or outdated information in HelpHub article
  • Video length: 5-10 minutes, the shorter the better (because no one wants to watch 1 hour of video just to report the typo)
  • Temporary storage: GDrive folder (a place where video author will host the video for review)
  • Final storage: WordPress.tv (hopefully we’ll get them captioned)

Keeping the track

Any member of Documentation team can record the video. In order to keep track of the process we have a dedicated document.

  • Video Title – proposed title of the video.
  • Docs Project – the name of the Docs project for which the video is being recorded (HelpHub, Code Reference, 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, 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 etc).
  • AuthorWordPress.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/ username of the team member who volunteers to record the video.
  • Status – the current state of the video.
    • Not assigned – Video is waiting for volunteer. Populated Video Title and Docs Project columns.
    • In progress – Video is assigned to volunteer who is in process of recording. Populated Author column.
    • Ready for review – Video is recorded and uploaded to temporary storage location, waiting to be reviewed. Populated Temporary URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org column.
    • In review – Video is being reviewed. Populated Reviewer column.
    • Waiting wp.tv – Video is reviewed, accepted and sent to wp.tv.
    • Finished – Video is published. Populated WordPress.tv URL column.
  • Temporary URL – the URL of the recorded video where it can be reviewed by other members of Docs team.
  • Reviewer – WordPress.org username(s) of the team member(s) who volunteers to review the video.
  • WordPress.tv URL – final URL for the video at WordPress.tv.
  • Comment – Comment by reviewers if anything should be modified/updated etc.

Prepare to record

Once you’ve selected the video to record, make sure to add your wp.org username and change video status to In progress in document for tracking all videos.

  • Create account at zoom.us, download and install desktop app.
  • Prepare the list of steps you want to perform. If you feel uncomfortable or nervous, you can write down the whole script for the video. You can ask someone from Documentation team to review it to make sure you’re covering all the important points.
  • Make sure your internet connection is stable and sufficient for recording live screen sharing.
  • You don’t have to use camera but make sure your microphone is working properly and the volume is at desired level. You can record a testing video. If you do decide to use camera consider changing the background.
  • Make sure you record in a quiet place, without interruptions and with minimum background noise (e.g. don’t record in a caffe or outside).
  • Open all tabs you’re going to use upfront so you don’t have to wait for loading pages (which will be slower than your usual page load speed) while recording.
  • Make sure you don’t expose any of yours or other people’s personal data (e.g. personal email, social networks, various notifications etc).
  • Share screen, hit record and good luck 🙂

Review

When you’re happy with your video, upload it to the Temporary folder. Add that URL to our document in Temporary URL column, change status to Ready for review and ask in 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/. for someone to review it. The more people see it, the better.

Once the team approves it, we can send the video to WordPress.tv and change status to Waiting wp.tv. After publishing at wp.tv, the status is changed to Finished.

Discussion

Please leave your thoughts, questions and suggestions in comments below. Thank you.

#contributing-videos

Agenda for Docs Team Meeting August 17, 2020

When: Monday, August 17, 2020, 15:00 UTC

Where: #docs channel on Slack.

Meeting Agenda

  1. Attendance
  2. Meeting Note-taker & Facilitator for next week’s meeting
  3. Project Updates
  4. External Linking Policy
  5. Docs Videos
  6. New Member Mentoring
  7. Monthly Coffee Break (August 2020)
  8. Google Season of Docs 2020
  9. Open Floor

#agenda, #meetings

Plan proposal for a new better structured Gutenberg developer documentation

I’ve recently volunteered to be 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 team repTeam Rep A Team Rep is a person who represents the Make WordPress team to the rest of the project, make sure issues are raised and addressed as needed, and coordinates cross-team efforts..

This is a proposal of next steps for a friendly Gutenberg developer documentation, useful for newcomers.
For more context about the current state about Gutenberg dev docs, and its challenges, read this: https://wptavern.com/wordpress-contributors-seek-sponsorship-for-improving-gutenberg-developer-docs.

The plan is to build on the existing documentation (https://developer.wordpress.org/block-editor/developers) to arrive at a better structured doc.

Here are some aspects that I thought the team could focus its discussions and reflections to get started.

Where are we at now?

It is essential to have an overview of existing documentation. Both the one present on https://developer.wordpress.org/block-editor/developers, on GitHub (if there is any), and also those in progress. This is to avoid dispersing our efforts, and to take advantage of the work already done by other contributors and volunteers.

What should be included?

In my view, one of the first step would be to agree on what should be included in the new documentation. There are currently many concepts (CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. concepts, APIs, etc…) that can be useful for developers using the 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. Some of them are already present in the current documentation. Others are in the codebase on the project’s 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/ repository.

A new structure?

The current structure of Gutenberg’s developer documentation is one of the aspects that makes it not friendly at all. For example, the home page of the documentation starts with the chapter “Creating Blocks”. A beginner is like thrown into the cauldron without knowing the prerequisites. Several contributors also address the question on GitHub here https://github.com/WordPress/gutenberg/issues/22151.

In this regard, I think we could learn from examples of documentation such as Gatsby.js https://www.gatsbyjs.org/docs (a quick start/tutorial, then a reference guide that discusses key concepts in a more or less defined order).

Cross-team collaboration

How do we want to collaborate with the different teams to make this happen? From here I see the core-editor team playing an important role, given their experience with the block editor development.

What’s next?

At this stage, we are only at the discussion stage, to see what is feasible and the best way to do it. If you are interested in helping with any of the steps, please feel free to comment. Also, if you have other points that you think are essential or need to be discussed in this plan, please feel free to mention them in your comments.

Season of Docs 2020

With the Season of Docs starting in a few weeks, I think this could be a great opportunity to move forward on that plan.

There are two projects in particular that could help:

  • Project #6 with @kenshino: Improve Existing Development Documentation and Handbooks and
  • Project #8 with @milana_cap: Extending Block Editor.

#block-editor, #documentation

Agenda for Docs Team Meeting August 10, 2020

When: Monday, August 10, 2020, 15:00 UTC

Where: #docs channel on Slack.

Agenda

  1. Attendance
  2. Volunteer Note-Taker (for this meeting)
  3. Volunteer Facilitator (for next week’s meeting)
  4. Project Updates
  5. External Linking Policy
  6. New Member Mentoring
  7. August Docs Team Coffee Break
  8. Open Floor

#agenda, #meetings