Onboarding to Documentation team

Here is some quick info you need in order to start contributing to Documentation team.

Accounts:

Places:

  • Blog – for meeting agendas and summaries (and anything related to Docs team).
  • Slack channel #docs – where meetings are happening (and all communication regarding the team itself).
  • GitHub repository – where issues for all documentation are reported, discussed and worked on.
  • Handbook – how to contribute to the Documentation team (it’s a bit out of date).
  • Style guide – for how to write WordPress documentation.

Meetings (alternating every week) on Tuesdays at 2PM UTC:

  • Regular meeting with agenda published on our blog.
  • Issues triage where we discuss issues from the GitHubGitHub GitHub is a website that offers online implementation of git repositories that 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.

Live onboarding sessions

We recorded onboarding sessions for everyone interested in getting started with the Documentation team. We know that our “Getting started” documentation is out of date and getting involved can be very confusing and frustrating so we hope to ease the process with these sessions.

Overview

Recording: https://wordpress.tv/2022/06/21/milana-cap-overview-onboarding-for-wordpress-documentation-team/

End user documentation

Developer documentation

Developer documentation – 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

Developer documentation – Common APIs handbook

Developer documentation – Code reference handbook

Developer documentation – 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 handbook

Developer documentation – Themes handbook

Contributor documentation – Documentation team handbook

If you have any questions or you’d like to have an “in more detail” session, feel free to leave the comment below.

Onboarding session for GitHub-related roles

The Documentation team recently revised team roles and areas of responsibility, which are documented in our handbook. While doing so, we identified a number of areas that are not project related but require enough work to be considered separate roles. Three of those roles (Issue triage facilitator, Issues coordinator, and Issues reviewer) are tight to GitHub issues and projects, and for those roles, we are going to run an onboarding session next week.

Session info:

Please note that there is no limit to how many people can perform the same role. If you are interested in getting involved, or not sure if you are interested yet, do try to join us and ask anything you want. If you can’t make it, the recording will be published together with all the other onboarding sessions.

Anything else you want to add or ask, you can do so in the comments below.

Summary for docs team meeting, January 24, 2023

Attendance

@leonnugraha @ninianepress @milana_cap @estelaris @ninthcoder @atachibana @femkreations

Housekeeping

Find the complete Transcript of the meeting on Slack.

Project checks

@milana_cap is working on crafting the WCAS Contributor Day task list.

@ninianepress finished issue #128.

Status update for HelpHub

@estelaris walked through the recently finished updates to the End-User Documentation (HelpHub, internally).

For full details of these changes, please see New look, new site, new HelpHub.

Status update for DevHub

@estelaris noted that @javiercasares (not in attendance) is the project lead for the Developer Handbook (DevHub, internally) redesign. She mentioned that the design has been finalized, and development work has begun.

Open floor

@milana_cap mentioned there is a new non-project role in the team that no one has been doing before: GitHub issues coordinator.

@femkreations would also like to note that issue gardening for v6.2 is in progress 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/ pull requests (PRs).

#docs, #meetings, #summary

X-post: WordPress.org Redesign Recent Launches

X-comment from +make.wordpress.org/meta: Comment on WordPress.org Redesign Recent Launches

New look, new site, new HelpHub

The docs team have been working hard on creating the end-user documentation or HelpHub. It took a very long time, 8 years to be exact since the project kicked-off, and we reached the goal. Follow the journey from these posts Kicking off HelpHub and New design for HelpHub in WordPress.org.

Introduction to the new Documentation site

The look changed to be in harmony with the rest of the 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/ template. The new features were created with the goal to facilitate search for end-users. Some of these features are:

  • a simplified sitemap divided into 4 categories and each categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. has several subcategories,
  • better definition between end-user and developers documentation, meaning that several articles will be moved into developers.wordpress.org in the next few weeks,
  • change to the menu item to documentation instead of support,
  • a new menu, breadcrumbs and other features

The four categories

The goal of the end-user documentation is to provide information to non-developers or new users so they try resolving their issue by themselves instead of going directly to the Forums.

To improve search, the team worked on reclassifying the articles into 4 main categories:

  • WordPress overview, where users can find general information about WordPress, versions, FAQs and resources.
  • Technical guides to help with installation, maintenance, and security.
  • Support guides to get familiar with the software and its features.
  • Customization where users can find instructions on how to use 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 and default themes.
Image showing the documentation landing page with its four categories and subcategories.

End-user and developers documentation

When moving the articles from the Codex, there was a separation between developer-focused and end-user-focused documentation. Yet, developer articles were still available within in end-user documentation.

To help make the distinction better, all developer jargon has been removed from end-user documentation and moved to developer.wordpress.org.

Documentation instead of support

The menu item was support, the docs team has been looking into changing the menu item into documentation. Documentation is better description than support.

Features

Breadcrumbs and a submenu

Users can use the breadcrumbs to return to a specific page, category or subcategory without navigating all the way to the landing page.

A new submenu was added for fastest linking to developers documentation, the forums and the docs team make blog.

Sticky table of content for articles

The new TOC in the articles is a sticky item with one link to take the user back to the top.

Video showing how the sticky TOC works within an article.

Props to @milana_cap@kenshino, and @atachibana for their direction on this project.

Props to @javiarce, @joen and @beafialho for their design guidance, help and commitment on the last stage.

Props to @ryelle for her amazing coding work.

Agenda for Docs Team Bi-Weekly Meeting January 24, 2023

The next meeting is scheduled with the following details:

When: Tuesday, 24 January, 2023, 02:00 PM UTC

Where: #docs channel on Slack

Agenda:

  1. Attendance
  2. Note-taker and facilitator selection for next meeting
  3. Facilitator selection for next triage meeting
  4. Projects checks
  5. Status update on DevHub
  6. Status update on HelpHub
  7. Open floor

If there’s anything you’d like to discuss on the open floor, please leave a comment below.

#agenda, #meetings

Support, forums, training or documentation

There are several ways to find information regarding the features or issues in WordPress and each one of them has a function and a time. This is a short explanation of what each means, the difference and when to use them.

What is what?

A good way to differentiate them is to define them and to provide use cases for each. None is better or worst than the other neither is any more or less important. It all depends on when they are used.

  • Support is 1:1, requires interaction and it is used for more urgent issues, whether is a chatbot or person and is immediate.
  • Forums are intended for broader help or best advice on specific topics. Most of the time is asynchronous but is monitored by a team or person, paid or volunteer. Most importantly, forums are community driven.
  • Documentation are basically instructions on how to do things. There is no interaction of any kind for questions. Literally, “what you read is what you get.”
  • Training creates lessons on topics. These can be on video or written form. Can be individual or part of a series. And training can be immediate or in the user’s own time.

Some use cases

Users require information for different reasons and search for it in different ways.

For instance, hosting companies use support, either by chat or call, to resolve a user’s issue. Whether is urgent or not, it usually is something that the user cannot solve by themselves or it has an immediate need for solution.

The forums are topical and in threads. They are very useful for discussions and to provide guidance over an issue or topic. Forums are monitored and conversation are mostly asynchronous. Some of the uses could be a school discussion group, product sales, best practices, product help, product how-to’s, etc.

When a user wants to learn fairly quick how to do something, following the steps in a documentation article is the best way. There are no interactions and the user reads it in their own time.

In opposition to wanting to deeply learn about a subject, then the user would search for a training lesson or course.

What can a user find 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/

WordPress.org does not provide support. There is no team that will reply to questions 1:1 at any time. Instead there are the Forums that are monitored by contributors, volunteer and paid, that reply to questions posted.

There is documentation for end-users and developers and there are training lessons offered in Learn.

It is a strong recommendation by the documentation team to stop using the word support and instead refer to each instance with their respective name.

Props to @milana_cap and @atachibana for the review of this article.

#docs

X-post: Proposal: [Experiment] Adopt Standardised Team-wide Project Management Tools – already utilised by other Make Teams for a Quarter.

X-comment from +make.wordpress.org/community: Comment on Proposal: [Experiment] Adopt Standardised Team-wide Project Management Tools – already utilised by other Make Teams for a Quarter.

X-post: Can you help with topics for the WordPress Developer Blog?

X-comment from +make.wordpress.org/core: Comment on Can you help with topics for the WordPress Developer Blog?

Development and design work continues on Helphub

Docs team, please refrain from updating/uploading articles on Helphub still. Work will continue until Friday 20 January.

I will update the team if we need more time.

For questions, 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.” @estelaris on docs 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.

#helphub

X-post: Advanced Administration Handbook: Status 2023-01-15

X-post from +make.wordpress.org/hosting: Advanced Administration Handbook: Status 2023-01-15