Ahmed Chaion 9:47 am on July 6, 2020
Tags: ,   

Agenda for Docs Team Meeting July 06, 2020

The next meeting is scheduled with the following details:

When: Monday, July 06, 2020, 15:00 UTC

Where: #docs channel on Slack.

Meeting Agenda

  1. Project Updates
  2. Categorization Project
  3. External Linking Policy
  4. New Member Mentoring
  5. Monthly Coffee Break
  6. Google Season of Docs 2020
  7. Open Floor

“Good code is its own best documentation. As you’re about to add a comment, ask yourself, “How can I improve the code so that this comment isn’t needed?” Improve the code and then document it to make it even clearer.” 

Steve McConnell

#agenda, #meetings

Ahmed Chaion 5:34 am on July 6, 2020
Tags: ,   

Summary for Docs Team Meeting on 29th June 2020

Attendance

@kenshino, @sukafia, @chaion07, @tacitonic, @atachibana, @kenshino, @sukafia, @chaion07, @tacitonic, @atachibana, @cristiano.zanca, @glorialchemica, @wpza, @mkaz, @crstauf, @milana_cap, @fahimmurshed, @Prubhtej_9, @estelaris, @tomjn, @timohaver, @yui, @mte90, @newyorkerlaura, @bph, @collinsmbaka, @ataurr, @softservenet, @imneet94, @abutalha94, @ibdz, @manthanadmane, @themiked, @mekalekahi.

Find the Agenda of the Meeting here.

Thanks to @kenshino for Facilitating the Meeting.

Notetaker & Facilitator Selection

Notetaker: @chaion07

Facilitator for the next meeting: @chaion07

Next Meeting will be held on: 06 July 2020

Find the complete Transcript of the meeting 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/..

Project Updates

@atachibana informed that 1014 out of 1070 pages had been completed. Currently the project is at 94.8% completion which is a 0.80% improvement from last week. He also thanked @stevenlinx for the contribution.

@bph reported that the Bee-Docs Meetings are held every Mondays at 14:00 UTC in #meta-helphub. Meetings start with the following items for contributor check-in:

  1. What have you been working on?
  2. What do you want to work on next?
  3. What are your blockers, (apart from time and 
  4. handling any blockers.

@bph also thanked @tacitonic for his committed work with new contributors, reviewing and publishing articles. The team is currently also working on the following:

  • Documentation for 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 so all contributors know how to work in it and so that we can all track what’s going on
  • WordPress.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/ documentation to fill some of our gaps and get a head start on some 5.5 features.

Categorization Project

@kenshino mentioned about @swissspidy‘s contributing to a XML Sitemap Documentation too.

@estelaris wrote a p2 post on classification and appreciated everyone who commented. The deadline for comments is set as 5 July 21:59 UTC. The team will again discuss this at the next weekly meeting on 06 July 2020. @estelaris and @ibdz will get together this week to continue with the design, leaving navigation aside until we resolve the classification.

@milana_cap is currently overseeing the work on 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 Docs for developers and she invited everyone to get involved with this tutorial prepared by @makz and it needs testing.

@makz added by saying that ‘The Create a Block’ Tutorial got merged in, but not linked up yet and still need to add Block Directory updates which you can browse on Github.

@christiano.zanca shared the news of Italian HelpHub being started. You can visit https://it.wordpress.org/support/ and experience it first hand.

External Linking Policy

@milana_cap is thinking of parts of the process as:

  • Proposal made by anyone (for external resource) – perhaps prepare a template
  • Review by Docs team members – need a list of criteria for this
  • Public post about proposal, review and reasons for acceptance/rejecting; and
  • Add resources to the public list of “Allowed resources”.

For the ‘list of requirements’ she’s thinking about the following types of resources:

  • Personal blogs
  • Tutorial sites (Udemy, Coursera, Skillshare, etc.)
  • Forums (Stack Overflow, TechRepublic, etc.)
  • Commercial blog (Not Allowed)

You can join the conversation by visiting the p2 post related to this topic. @milana_cap is considering writing another p2 post on this.

New Member Mentoring Team

@sukafia reported that the Mentoring Team is actively reaching out and checking up on new members. The team is ensuring that every member gets a Welcome Message and is provided with links to helpful resources and guidance relevant to #docs. 5 new members have joined since last week, raising the numbers for this month to 68. The ‘New Member Mentoring Team’ will be having a meeting  to discuss our next steps & ways to improve the mentorship initiative.

You can contact @sukafia, @softservenet, @tacitonic or @Prubhtej_9 with your ideas, suggestions and comments.

Monthly Coffee Break (June 2020 Updates)

We have 12 people joining in the Monthly Coffee Break for June where we have discussed informal topics and tried to understand each other. We have received positive feedback from participants so @sukafia will create another Doodle for the month of July and share it in the #docs channel. 

@chaion07 will volunteer alongside @sukafia to continue writing a monthly summary piece on the coffee break in the form of a p2 post.

Google Season of Docs

All Technical Writers who are interested to participate in the Google Season of Docs for 2020 are requested to comment in this p2 post. A lot of the mentors have their designated Google Form or other means of communication to submit their ‘expression of interest’ by the technical writers. Technical Writers are requested to follow the guidelines provided by the Mentors for their specific project idea as mentioned in the post. You can also comment in the #docs channel and tag your Mentor for faster communications if needed.

End of Meeting Notes

#meetings, #notes

Ahmed Chaion 5:22 am on July 6, 2020
Tags: ,   

Agenda for Docs Team Meeting June 29, 2020

The next meeting is scheduled with the following details:

When: Monday, June 29, 2020, 15:00 UTC

Where: #docs channel on Slack.

Meeting Agenda

  1. Project Updates
  2. Categorization Project
  3. External Linking Policy
  4. New Member Mentoring Team
  5. Monthly Coffee Break (June 2020 Update)
  6. Google Season of Docs 2020
  7. Open Floor

#agenda, #meetings

Timi Wahalahti 6:59 pm on July 2, 2020
Tags: ,   

X-post: WCEU 2020 Online Contributor Day: Feedback and achievements

X-post from +make.wordpress.org/updates: WCEU 2020 Online Contributor Day: Feedback and achievements

Milana Cap 3:13 pm on July 1, 2020
Tags: make.wordpress.org/themes,   

X-post: Block-based Themes Meeting Agenda for July 1, 2020

X-comment from +make.wordpress.org/themes: Comment on Block-based Themes Meeting Agenda for July 1, 2020

Jon (Kenshino) 3:08 pm on July 1, 2020
Tags:   

Updated Team Badges

Today @atachibana @milana_cap and I got on a call and went through the list of people that had Doc Team Badges.

We removed 16 in-active people and added gave 2 people the team badge. We’re now at 20

I have also give @milana_cap and @atachibana the ability to manage both the Docs Team and Contributor badges.

If you’ve lost the badge and feel like that was in error, please feel free to 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 in #docs

Tim O'Haver 5:15 pm on June 23, 2020
Tags:   

Summary of Docs Team Meeting for June 22, 2020

Attendance

@Ataurr @bph @chaion07 @collinsmbaka @estelaris @FahimMurshed @ibdz @joyously @Kenshino @Leslie @MakeWebBetter @manthanadmane @mekalekahi @milana_cap @PiyushChetwani @Prubhtej @saiftheboss7 @sasiddiqui @softservenet @sukafia @tacitonic @themiked @timohaver (23 people attending)

Meeting 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.

Meeting Agenda: https://make.wordpress.org/docs/2020/06/20/agenda-for-docs-team-meeting-june-22-2020/

Meeting Transcript: https://wordpress.slack.com/archives/C02RP4WU5/p1592838088036700

Meeting Facilitator: @chaion07

Meeting Notes by: @timohaver

Notes Reviewed by: @chaion07 

Facilitator for Next Meeting: @Kenshino

Follow the docs team meeting on the WordPress.org Slack workspace by joining the # docs channel.

Project Updates

Prior to the meeting, @atachibana reported 1006/1070 (94%) completed for the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. and re-routing of Codex to Code Reference for Functions. He recognized @stevenlinx for their collaboration processing complex cases, and @obt28 for work on 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..

@bph completed the first meeting for 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 End-User Documentation team. The team meets again next Monday (1400 UTC) in the #meta-helphub channel. 

Categorization Project, Alterations Workflow

@estelaris has a draft post in-progress. She expects to finish it no later than Wednesday, and requested discussion and feedback as comments on the post.

External Linking Policy: Trusted Sources

@milana_cap authored a detailed post on this topic. She has been fielding questions, and this is helping to shape some early ideas about workflows. More participation is better. Everyone is invited to contribute ideas and questions as comments on the post. For updates, follow the #external-linking-policy tag.

New Member Mentor Training

@sukafia reported that 63 new members have joined the docs channel this month. The New Member Mentoring team has made follow up contact with all the new members. @sukafia thanked @tacitonic @Prubhtej, and @softservenet for their contributions to the team effort.

Monthly Coffee Breaks/Zoom Sessions

The June Coffee Break is set for this Thursday (June 25) at 1500 UTC.

Open Floor

@joyously referred to a question previously asked about the licensing “of the various docs: what is it and where is it stated”, inquiring if it was ever resolved or posted. @Kenshino answered that all docs in question were GPLv2, with permission to multi-license as-needed. He offered to create a page for the sake of clarity. The exchanges that followed weighed the merits of adding licensing content to post and page footers vs. creating a page. 

@joyously is finding the new order of DevHub sections to be less useful than the prior version. She cited a closed ticket that resulted in the change. @Kenshino is pursuing a response from @atachibana.

@manthanadmane and @softservenet inquired about creating a dedicated 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/. channel for new member mentoring. @Kenshino asked to address the question at the next weekly meeting.

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.

#meeting-notes

Estela Rueda 2:29 pm on June 22, 2020  

Exploration of a new classification for user documentation

Background

While working on a new design for HelpHub or documentation in 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/, we discovered that the implementation of a menu or a table of contents was difficult because the articles were included in several categories.

Documentation is maintained manually by contributors and it is being moved from the old Codex. The structure is 17 years old and as WordPress develops and grows, the categories that worked 5 or 10 years ago are not necessarily the same that work now.

In order to continue with the design of documentation, we need to define a documentation structure that is clear and fulfills the user’s needs.

Problems with the actual categorization

The issues below affect the way users consult the articles in the documentation section.

  • There is a lack of definition of user personas. 
  • Search is not user-friendly because navigation is not clear, making article discoverability challenging. 
  • Inside a categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. with several pages, articles jump order, making navigation confusing.
  • Some titles are not descriptive enough or use only one word.

What are we looking for

It is important to define first what the goal is for the documentation structure in order to define the categories. Envisioning what our ideal documentation section should look like:

  • It should be easy to navigate: a user should understand where they are.
  • Categories should be broken into subcategories to ease mobile navigation.
  • Categories should be descriptive enough to quickly answer the question: “where does this article go?”
  • It should be reliable: if an article is not found where it should be, it means that the article simply doesn’t exist
  • Titles should be descriptive enough for any type of user to understand what the article is about.
  • Maintenance or updating of the articles should be easy with a clear documentation structure
  • The structure should allow the incorporation of new categories or subcategories as the software develops.

The docs team worked on creating some stories that can help us verify if the proposed solution will work. You can find the complete list of stories here:

  • If I am new to WordPress, how do I know if it is the right CMS for my project?
  • If I am a blogger who receives many comments, is my data secure in WordPress?
  • If I am not a developer, can I still create a website and add my own branding?
  • If I am a business owner, can I sell products in WordPress?
  • If I am a website designer, where can I find information about new releases and upcoming features?

What documentation looks like now

So far, there are 171 articles being moved from Codex into HelpHub. Separately there are new articles being written about 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, so far 40 articles have been added and there are plans for more.

In the image below, we can see a snapshot of how articles are included in several categories. At the moment, the articles were arranged in alphabetical order because the articles jump order while scrolling through the pages:

A better view of the list can be found here.

Example scenario

Let’s review an example from the image above where the articles jump order inside a category with multiple pages.

In the video below, we are looking at the category Getting Started. A session was recorded following the Next Page link at the bottom of the page and then returned to the first page following the Previous Page link. The first page at the beginning has different articles than the first page that we returned to.

What it is like on a computer

The first page begins with the following list of articles:

  • Appearance Menus Screen
  • Backing Up Your WordPress Files
  • Pages Add New Screen
  • New to WordPress – Where to Start
  • Administering Your Blog
  • Resetting Your Password
  • Creating a Search Page
  • Managing Plugins

We navigated to the last page via the Next Page link at the bottom of the page and then returned to the first page, using the Previous Page link.

When arriving to the first page, the list of articles is different from what we have above:

  • Comments in WordPress
  • phpMyAdmin
  • Creating a Static Front PageStatic Front Page A WordPress website can have a dynamic blog-like front page, or a “static front page” which is used to show customized content. Typically this is the first page you see when you visit a site url, like wordpress.org for example.
  • Users Your Profile Screen
  • Update Services
  • Settings Writing Screen
  • Administration Screens
  • Giving WordPress Its Own Directory
  • Settings Reading Screen
  • Dashboard Screen

What it is like on mobile

On mobile, the situation is the same. 

Looking into the future

Target audience

As mentioned before, the end-user of documentation is not well defined but the existing documentation can shed some  light into identifying who the users are.

Who is the content intended for? 

From the stories written, we can identify some groups, but we have not explored the many user personas that access the documentation. Here are some examples:

  • New users looking for a CMS to build a website.
  • Bloggers/website designers that want to customize a site.
  • Content creators looking for content to write tutorials/posts.
  • WordPress consultants that provide services to their clients.
  • Others?

Type of content

In order to define a navigation structure that suits the project and allows for growth, we need to explore information pillars. Pillars shouldn’t be more than 4 or 5, as these can be split into categories and subcategories to form a logical navigation structure. These are suggestions for information pillars:

  • WP basics – overview, features, history, glossary, semantics, contributing.
  • Technical documentation: installation guides, requirements, best practices, technical how-to, security, troubleshooting.
  • Support documentation – dashboard structure, user permissions, screens, media screens.
  • Project related documentation – customization, themes & plugins, design how-to’s (blocks)

Relation to time and development

There are articles that have been superseded by new development and are either no longer relevant to the software itself or must be updated. We need to include 4 buckets where we should add articles:

  • No longer relevant or valid
  • Need update
  • Convert from Codex as is
  • Create new documentation

Next Steps? 

The docs team will continue working on defining the user personas, as well as the information pillars.

We plan on having a proposal on documentation structure that includes clear navigation and new classification, by the end of the summer.

If you would like to contribute to the project, leave your comments. Comments will be discussed during the #docs team meetings on Mondays at 15:00 UTC

Ahmed Chaion 1:04 pm on June 20, 2020
Tags: ,   

Agenda for Docs Team Meeting June 22, 2020

The next meeting is scheduled with the following details:

When: Monday, June 22, 2020, 15:00 UTC

Where: #docs channel on Slack.

Meeting Agenda

  1. Attendance
  2. Note-taker & Facilitator selection (for Next Meeting)
  3. Project Updates
  4. Categorization Project, Alterations Workflow
  5. External Linking Policy– Trusted Sources
  6. New Member Mentor Training
  7. Monthly Coffee Breaks/Zoom sessions
  8. Open Floor

“All the details of life and the quirks and the friendships can be laid out for us, but the mystery of the writing will remain. No amount of documentation, however fascinating, can take us there.”

~ V. S. Naipaul

#agenda, #meetings

Milana Cap 4:06 pm on June 15, 2020  

Summary for Docs Team Meeting: 15 June 2020

Attendance

@collinsmbaka @atachibana @kenshino @bph @chaion07 @tacitonic @MakeWebBetter @timohaver @saiftheboss7 @lvg2013 @sasiddiqui @manthanadmane @audrasjb @fierevere @kmeze @immeet94 @fahimmurshed @pratikchauhan @themiked @nullbyte @joyously @crstauf @milana_cap

Meeting transcript: https://wordpress.slack.com/archives/C02RP4WU5/p1592233201335300

Next meeting

Facilitator: @chaion07

Date: Monday, June 22, 2020, 15:00 UTC

Project Updates

Categorization Project, Alterations Workflow

@estelaris couldn’t make it to the meeting due to health issues. Get well soon Estela <3

Google Season of Docs

For all the GSoC potential tech writers, @kenshino will be replying to any open questions end of this week if mentors don’t get a chance to, it’s highly recommended for all mentors to make direct and public replies so that other scan read and benefit from it too. There are two posts with questions/comments from potential tech writers – https://make.wordpress.org/docs/2020/05/12/season-of-docs-technical-writer-exploration-may-11-june-8/ and https://make.wordpress.org/docs/2020/05/01/season-of-docs-project-list-idea/

External Linking Policy – Trusted Sources

We need to specify the criteria for becoming labeled as “trusted source” in order to avoid misuse. Dedicated p2 post is a place for posting all your thoughts and questions on the subject. Follow #external-linking-policy tag for updates.

New Member Mentor Training

@sukafia wan’t available for the meeting. @tacitonic reported that the Mentorship team (@sukafia, @tacitonic, @softservenet) is regularly messaging and assisting new members. Since past week over 60 new members have been contacted.

Monthly Coffee Breaks/Zoom Sessions

The Doodle is still up for everyone to vote for the next meeting time:
https://doodle.com/poll/ds3dadnzzcwdz63k

Open Floor

@joyously reported that Documentation team’s help is needed in forum’s topic: https://wordpress.org/support/topic/database-erd/

@audrasjb proposed documentation for Auto-update feature and re-organising Site Health documentation. There is a Trac ticket for improving support for site health issues on HelpHub. @audrasjb volunteered to work on drafts. @milana_cap volunteered to review the drafts.