Chloe Bringmann 8:36 pm on May 12, 2020  

Season of Docs: Technical Writer Exploration, May 11-June 8

It is with excitement that WordPress is officially participating in Google’s Season of Docs 2020.

From May 11-June 8, technical writers are welcome to review the proposed list of project ideas and ask questions related to proposal development. Mentors, thank you for being on hand to help think through project proposals related to our initial ideas or ones the writers may devise. Technical writer applications are due July 9th; We look forward to working with you!

What’s next?

Technical writers interested in working on one of our project ideas, please add your questions as a comment to this post.

Chloe Bringmann 1:55 pm on May 1, 2020  

Season of Docs Project List Idea

Below is a list of projects that are put forward for technical writing collaboration in this year’s Season of Docs.

As of a reminder of who is involved:

Projects

Project One: @kenshino

Project name: A full and renewed set of documentation style guide
Description: We’ve written some style guides along the way but many of those applied to specific handbooks or projects we worked on.

That said, there is not a unified style guide nor is it actually complete.

We propose developing a new style guide while fixing up older ones or simply adopt a great existing one with compatible licenses.

Related material:

Project Two: @makewebbetter

Project Name: Most Popular Security Attacks

Description: There are plenty of security breaches issues reported. We plan to create documentation of some of the most common issues with suggested fixes so that users can learn and solve their issues.

Related material:

  • Link to the open source project that needs documentation – https://wordpress.org/support/article
  • Update existing documentation – https://wordpress.org/support/article/brute-force-attacks/
  • We can have documentation with two to three attacks issues, explain what effect they have on websites, how to prevent, and the fastest way to fix and protect your website.

Project Three: @kenshino

Project name: Tracking Doc Suggestions / Updates
Description: We do not have a unified tracking system for when a doc needs updates. People do it on Meta Trac (which is really for code changes to WordPress.org), report them on Slack, and sometimes via Twitter. It’s impossible for people to know if a doc is going through updates or is simply outdated. Some projects use Trello for short term purposes. Some projects use GitHub.

We really ought 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.

Related material: 
None at the moment. It’s new!

Project Four: @johnzenith

Project Name: WordPress Development Configuration Guide

Description: Code misconfiguration and setup can introduce security bridges and break security endpoints, thereby leaving the door open for malware infections and cryptographic attacks.
Creating a configuration guide or overview for developing in WordPress will be very useful. Some of these exist but are not organized or put together in a single place. For example, the configuration Guide will have several sections as files and directories, debugging, nonces, database, WordPress salt, constants, queries, global vars, htaccess, password, https, etc.

Related Material

Project Five: @asif2bd

Project Name: Curate Existing HelpHub Article To Create Pillar Contents
Description: We are continuously creating more content in HelpHub, but basic questions like “Locally Host WordPress” or “How To Secure WordPress”, are answered with separate CPT and not one article to answer completely or links to existing content. While the current configuration is good for SEO, it is confusing for our users.
Related material:

  • Link to the open source project that needs documentation: https://wordpress.org/support/
  • I am proposing ‘Pillar Content” that will be curated collection of existing content that will direct guide users in finding more authenticated information. Like “How To Secure WordPress” will give precise guideline and will link and resources from following contents

Include links to similar documentation in other projects:

Project Six: @kenshino

Project name: Improve Existing Development Documentation and Handbooks
Description: We have a lot of developer documentation. Core’s documentation is mostly automated.

However handbooks that describe how one would create a theme, make a plugin, use the REST API or automate things via the CLI 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.

Related material:

Project Seven: @estelaris

Project Name: Improving article discoverability

Description: During the design process, it was discovered that categories are not used to classify documentation articles and an article may have more than two categories instead of using tags to related articles. This makes it difficult for users to search, as they can click on a category > article, and hit the return button only to find themselves in an entirely different category. Another issue is the titles which in some cases do not properly describe what the article is about.

Related material:

Project Eight: @milana_cap

Project Name: Extending Block Editor

Description: Documentation on developing on top of Block Editor is, depending on the topic, either scarce, outdated, or non-existent. Considering that Block Editor is a significant language leap for WordPress developers, I think 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:

Project Nine: @marcio-zebedeu

Project Name: Write your first WordPress Theme

Description:
It is not enough to say that creating a WordPress theme is easy if we do not show it in practice in the documentation. Currently we have a good article on how to start with WordPress, I believe we could do more to make the theme development manual better, as it does not provide a kind of tutorial that really ends with the creation of a functional theme.

  • Related Material:
  • Link to the open source project that needs documentation: https://wordpress.org/support/article
  • Updates to existing documentation:
  • https://developer.wordpress.org/themes/getting-started
  • It can be divided into stages: Creating a html template, adding simple styles, separating those from html files and finally converting to one of the templates for the WordPress theme

MakeWebBetter 9:31 am on May 13, 2020
Tags:   

Summary for Docs Team Meeting: 11 May 2020

Attendance

@makewebbetter @atachibana @mkaz @marcio-zebedeu @annezazu @milana_cap @chaion07 @bph @ibdz @collinsmbaka @kartiks16 @nobnob @mukesh27 @felipeloureirosantos  @wizzard_ @fahimmurshed  @ataurr @netpassprodsr @estelaris @crstauf @timohaver @immeet94 @softservenet @kulsumsiddique @thisisyeasin @sukafia @sasiddiqui @leogermani @themiked @kenshino @rabbirshad199621

Agenda

You can find the Agenda here.

Notetaker: @makewebbetter & @thisisyeasin

Notes Reviewed by: @chaion07

Facilitator: @chaion07

Facilitator for Next Meeting: @estelaris

Follow the meeting on the Slack channel for Docs

Project Updates

@leogermani provided updates async to the meeting:

  • Common APIs – migrate HTTP from plugins Handbook
  • Migrate hooks
  • Organize workflows within the Handbook

@atachibana reported that for re-routing of the Codex page to Code Reference for functions, 908 out of 1064 (84.9%) have been completed. He thanked @collinsmbaka and @stevenlinx for the jump from 67.4% recorded last week.

@themiked reported the migration to single blocks continues in the plugin handbook and he identified a few things that don’t belong to the handbook. He also identified terminology disparities that he is tracking and trying to unify for example “meta-data” vs “metadata”.

@bph added a few more categories under “Block Editor” to the articles. Both @bph and @estelaris are collaborating with each other to complete the review process. However @estelaris believes there might not be further update for reclassification until WCEU 2020 which happens in 3 weeks.

WCEU Online Contributors Day

@milana_cap emphasized on “Getting started at a Contributor Day” page to be completed by this week and asked for suggestions from new contributors as well as others. She further added by referring to the Polyglots Team where they had used cool tools in their templates such as Translation Statistics tool, Translation Consistency tool etc. @leogermani & @wizzard_ volunteered to help. (Ref)

@milana_cap also proposed for scheduling a meeting between 25 May & 3 June using Slack for new contributors. She further added by saying that this meeting could be a great opportunity for @sukafia’s mentorship program. @estelaris pointed out that the first meeting should also be for the on-boarding of the new contributors and it is important that everyone has their own Slack account and access to Making WordPress work space. Following the first meeting there should be a second meeting on the WCEU 2020 contributors day after the opening remarks but using video. @estelaris also reminded us that the deadline for video submission for the individual “Making WordPress” teams is Thursday and it would be better if a Team Rep created the video. Update async to the meeting: @milana_cap had already prepared a video and shared with the team for feedback.

Update async to the meeting: @leogermani edited the page and made a comment on p2: https://make.wordpress.org/docs/2020/05/09/docs-team-preparation-for-wceu-2020-contributor-day/

@milana_cap thought that it would be good to include all the tools we are using which can be found in Workflow -> Reporting an Issue page.

Creating a task list for WCEU 2020

@milana_cap emphasized on creating task lists for both beginners and advance contributors and requested everyone to define what they want to do during the day for the project. Additionally, she will create a new P2 post which would include instructions with links. Here is the action plan:

Monthly Coffee Breaks/Zoom sessions

@chaion07 reported that the docs team had their first Virtual Coffee Break with several people attending. The participants spoke about how they are coping with the quarantine and isolation and what we are doing to keep ourselves busy, @sukafia had facilitated the last Coffee Break. The coffee break would take place monthly over Zoom. @sukafia will create another doodle for everyone to participate for the scheduling and accordingly be notified through the Slack channel.

New members Mentor training

@sukafia has reached out to new members and reported that some of them would start contributing within the week. He also recommended @lvg2013 that she wants to contribute to the block editor for docs. The plan for new contributors is that they’ll contribute using Google docs and once reviewed, they’ll be given guidance for their contribution to prosper ahead.

Open Floor

@milana_cap proposed that we should officially decide on  External Linking in Docs Policy but @kenshino suggested that he will make a decision by next week after reviewing all the comments. @themiked also posed the following points async to the meeting on external linking with the following questions.

  • Who has the authority to add a link to a page?
  • Who has the authority to remove a link?
  • If I (me personally) write an article on my own site and then link to it, is that seen as a conflict?
  • Will we police the links to ensure they are still valid?
  • Will we police the links to ensure the content has not changed, such as by the result of a domain transfer?

@makewebbetter inquired why are we not writing excerpt in all articles listed inside categories such as advanced-topics and when we called excerpt in the code template of this archive page we used to call excerpt but as the excerpt field left blank so first para content will automatically be fetched.

Transcript

https://wordpress.slack.com/archives/C02RP4WU5/p1589209219221400

Please feel free to suggest any changes to the meeting notes by mentioning in comments !

@makewebbetter

#summary

Timi Wahalahti 12:26 pm on May 11, 2020
Tags: ,   

X-post: WCEU Online 2020 Contributor Day: Submit your introduction videos, office hours times and introductory session needs this week

X-post from +make.wordpress.org/updates: WCEU Online 2020 Contributor Day: Submit your introduction videos, office hours times and introductory session needs this week

Ahmed Chaion 10:48 am on May 10, 2020
Tags: ,   

Agenda for Docs Team Meeting May 11, 2020

Our next Meeting is scheduled with the following details:

When: Monday, May 11, 2020, 15:00 UTC

Where: #docs channel on Slack.

Meeting Agenda

01. Attendance

02. Note-taker & Facilitator selection for Next Meeting

03. Project Updates

04. WCEU Online Contributors Day

05. Categorization Project, Alterations Workflow, User Stories (discussion)

06. Handbook Revamp

07. New Member Mentor Training

08. Monthly Coffee Breaks/Zoom sessions (update)

09. Open Floor

“Even though it is better if the system can be used without documentation, it may be necessary to provide help and documentation. Any such information should be easy to search, focused on the user’s task, list concrete steps to be carried out, and not be too large.” 

~ Jakob Nielsen

#agenda, #meetings

Milana Cap 4:28 pm on May 9, 2020
Tags: , wceu   

Docs Team Preparation for WCEU 2020 Contributor Day

WCEU 2020 will be held online and it will have the biggest Contributor Day done fully remote. This is challenging in many ways for everyone involved: organisers, team reps and teams, new contributors.. 

To help prevent some of foreseen problems, organisers offered a set of tasks for each team to be done in following days. 

Here’s what we have to do:

  1. Update the Getting Started at a Contributor Day page in handbook (polyglots team made a good example)
  2. Schedule European timezones friendly office hours taking place in Slack between 25 May and 3 June, targeted to answer questions from new contributors and help them to set up tools. This is a good opportunity to test our mentorship program.
  3. Choose an experienced contributor(s) from the team to record a short video introduction about the team. These videos will replace the traditional live introductions given during opening remarks and also used in the Contributor Day Orientation tool. Detailed guides for making these videos will be shared in the coming weeks. 
  4. Divide the tasks planned for the day between ‘good first tasks’ and ‘tasks for experienced contributors’. Make sure that every new contributor gets an easy task first. An example of how the Community Team does this: Call for ideas and plans for the day.
  5. Choose at least two experienced contributors to facilitate the work during the day, to help new contributors and to answer their questions quickly and happily.
  6. Plan an introductory session to help onboard new contributors to your team. The team-specific introductory sessions will take place after opening remarks. Another one for our mentorship program.
  7. Make a rough estimate of how many working groups your team needs during the day. Working groups are contributors working together with specific tasks or features, who will need a dedicated virtual table/space for discussion. This information is crucial for WCEU in planning platform usage and layout.

Leave your thoughts and suggestions in the comments and we will discuss these in the next meeting, on Monday 11th May.

#contributor-day, #wceu

MakeWebBetter 11:58 am on May 6, 2020
Tags: , ,   

Summary for Docs Team Meeting: 4 May 2020

Attendance

@milana_cap @chaion07 @makewebbetter @estelaris @crstauf @sukafia @adamsilverstein @nobnob @ibdz @johnbillion @atachibana @bph @cbringmann @themiked @sasiddiqui @audrasjb @mukesh27 @kartiks16 @collinsmbaka @immeet94 @mkaz

Agenda

source

  1. Attendance
  2. Note-taker & Facilitator selection for Next Meeting
  3. Project Updates
  4. Categorization Project, Alterations Workflow, User Stories
  5. Handbook Revamp
  6. Season of Docs
  7. New Member Mentor Training
  8. Monthly Coffee Breaks/Zoom sessions
  9. WCEU Online Contributors Day
  10. Open Floor

Notetaker: @makewebbetter
Notes Reviewed by: @chaion07
Facilitator: @milana_cap

Facilitator for Next Meeting: @chaion07
Follow the meeting on the Slack channel

Project Updates

@bph reported on the following: (Ref)

  • Last month was all about blocks with a “Sprint” where I contributed 6 days in a row, updated 3 pages and created 4 more.
  • Secondly, collaborated with @Pascal on the list of updated pages for the #Polyglots team to include changelog. Moreover, converted reusable blocks to regular blocks for the same team.
  • Next sprint: Wednesday through Friday.

@atachibana reported on the Re-routing of the Codex page to Code Reference for Functions with 721 out of 1064completed which is approximately 67.4%. He was happy with the improvement and considered this as a big jump from 54.5% compared to last week . He also expressed his thanks to @stevenlinx and @collinsmbaka. (Ref)

HelpHub development: @milana_cap informed Table styles patch is up, wonderful @sergey pinged, we’ll have fix soon https://meta.trac.wordpress.org/ticket/5033

Plugin Handbook: @themiked reported plugin handbook not ready this week, although PR to fix the wpdb docs pulled from source have been merged into the next release.

Categorization Project, Alterations Workflow, User Stories

@estelaris reported that work is still in process for P2 Updates. No further updates for this week.

Handbook Revamp

@milana_cap completed Reporting an Issue page from the Docs team Handbook.

New page to work upon while we are on workflows would be Facilitating Documentation Table at Contributor Day

Season of Docs

@cbringmann confirms regarding linking all projects to google which are listed here 

The list for Mentor Applicants are:

@cbringmann also mentioned that we have to wait for Google to get back to us, then will have a list of projects which got selected so that we can move to the next step. The Linked Project List can be found (here).

New members Mentor training

@sukafia suggested that we should have a meeting within this week for the new member’s Mentor training.  He also spoke with @atachibana and collected some ideas on how to help new members contribute to devhub as @atachibana had shared a list of projects new members can easily contribute to. 

Monthly Coffee Breaks/Zoom sessions

@sukafia had created a Doodle for coffee break and requested all of us to please select the preferred slot according to availability.

WCEU Online Contributors Day

@milana_cap has started writing a p2 post for WCEU Online 2020 Contributors Day

Open Floor

@audrasjb announced that French Documentation team had successfully translated 76 Helphub pages which actually covers 36.3% of total, now moving forward to make those pages publicly available for all French users. He also expressed his gratitude to everyone who worked on HelpHub internationalization and thinks that it was fantastic.

@milana_cap urged one of the Docs Team members to maintain the developer’s Block Editor documentation. She also added by saying if you’re knowledgeable and experienced with developing on top of the block editor then you should try and help. @makewebbetter offered to help and @milana_cap would look after it.

#meetings, #summary

Milana Cap 8:47 pm on May 3, 2020  

Agenda for Docs Team Meeting 04th May 2020

Next Docs meeting will happen on Monday, 04 May 2020, 15:00 UTC in #docs Slack channel.

  1. Attendance
  2. Note-taker & Facilitator selection for Next Meeting
  3. Project Updates
  4. Categorization Project, Alterations Workflow, User Stories
  5. Handbook Revamp
  6. Season of Docs
  7. New Member Mentor Training
  8. Monthly Coffee Breaks/Zoom sessions
  9. WCEU Online Contributors Day
  10. Open Floor

May the 4th be with you.

MakeWebBetter 3:12 pm on April 30, 2020
Tags: ,   

Summary for Documentation Team Meeting 27 April 2020

Attendance

@chaion07 @kenshino @milana_cap @estelaris @netpassprodsr @joyously @sukafia @makewebbetter @cbringmann @rabbirshad199621 @iamshubhamnigam @atachibana @themiked @softservenet

Agenda

source

  1. Attendance
  2. Note-taker & Facilitator selection for Next Meeting
  3. Categorization Project, Alterations Workflow, User Stories (discussion)
  4. Handbook Revamp
    • Homepage Update
    • Deadline for next 2 to 3 pages
  5. Project Updates
  6. Season of Docs
  7. New Member Mentor Training
  8. Tracking Slack Comments
  9. Monthly Coffee Breaks/Zoom sessions
  10. WCEU Online Contributors Day
  11. Open Floor

Notetaker: @makewebbetter
Notes Reviewed by: @chaion07
Facilitator: @chaion07
Facilitator for Next Meeting: @milana_cap
Follow the meeting on the Slack channel

Categorization Project, Alterations Workflow, User Stories

@estelaris completed 63 stories so far.(ref).

Instead of a zoom meeting, write-up is recommended by @kenshino ref and @estelaris agreed to complete that by this week. @chaion07 also ready for assisting as a supporting hand.

Handbook Revamp

@milana_cap provided a Handbook document – here, this document is not finished as she doesn’t have workflows for some projects, she’ll list once the draft is finished.For the missing ones she recommended “Report in Slack” as the default option.

Project Updates

@atachibana reported on thee-routing of the Codex page to Code Reference for Functions as 583 out of 1069 (54.5%) had been completed. He also felt that it was a considerate jump from 46.6% from last week by reaching 50% and more.!He also expressed his thanks to @stevenlinx, @collinsmbaka, and @immeet94 Ref

Season of Docs

After discussion and to considering a point that we need time to select the project ideas the deadline for project ideas submission was decided as 30th of April UTC 11:59

Recommended format for posting project ideas

Project name: Choose a concise but descriptive title.
Description: A longer description of the documentation work required. Describe your initial idea in detail. Offer opportunities for any interested technical writers to expand or refine the idea.
Related material: if any

All mentors are required to post at least one idea, and we need to choose 6 projects from 12 and 2 mentors per project.
And submit your ideas here before the deadline- 30th UTC 11:59

New members Mentor training

@sukafia shared the link to the working document – here 

Including the tracking sheet for new members  – here 

He addressed that the team is welcoming new members alongside @softservenet @netpassprodsr and @milana_cap to make this happen. (ref)

Slack Comment Tracking

@kenshino suggested this to be proposed by one of the mentors as a project in the Season of Docs.

Monthly Coffee Breaks/Zoom sessions

@sukafia suggested if we can play around with features like Zoom breakout rooms and a few other features that’ll allow us to get to know each other in a fun way. But he wasn’t sure on the scheduling of the coffee break.

He will create a  Doodle Poll for the schedule selection to the Coffee Break and update us regarding this. 

WCEU Online Contributors Day

@milana_cap is going to write a post on WCEU Online Contributor Day on behalf of the Docs Team.

Open Floor

@joyously pointed out that there have been several questions here about the look of the Roles and Capabilities page, and towards the recent ticket that was posted. Was it that the table styles were lost? Did this get fixed? @milana_cap replied that she was on it as it hadn’t been fixed yet.

@netpassprodsr wanted to ask what was needed to move the doc’s page reformat initiative forward referring to the forums page wordpress.org/support/forum?

#meetings, #summary

Chloe Bringmann 2:50 pm on April 27, 2020  

Season of Docs: A Call For Projects!

Thank you to all who responded to @kenshino initial call for mentors as we prepare to participate in this year’s Season of Docs. As this season’s primary administrator, I am looking forward to working with you all!

Mentors

For those listed below, please be sure to familiarize yourself with the responsibilities of being a mentor and apply before the deadline of May 4th 20:00 UTC. If you have any questions, @kenshino will be acting as a support throughout the mentoring process.

Next Step: Project Ideas List

Our next step is to create a project ideas list. This list should include documentation projects that would benefit from the work of a technical writer. Each of these projects will need the guidance of two mentors. Please add your project ideas as a comment below by Thursday, April 30th UTC 11:59.