Write description for onboarding sessions

[zzap]

Onboarding session videos are great and useful, but in a situation like a Contributor Day, watching videos might not be the best way or even possible.

Writing a description for the video in the form of a step-by-step guide would be more helpful in this scenario.

• Overview - https://make.wordpress.org/docs/handbook/get-involved/onboarding-sessions/overview/
• End user documentation
• Plugin handbook
• Common APIs handbook
• Code reference handbook
• Block editor handbook
• Themes handbook
• Documentation team handbook
• Github related roles
• Advanced Administration handbook - video doesn't exist 😱
• Updating screenshots - https://make.wordpress.org/docs/handbook/get-involved/onboarding-sessions/updating-and-creating-new-screenshots/

Descriptions should live in Documentation team handbook under Get involved - create a new page, "Onboarding sessions".

TODO: When done, update onboarding post with links to these new pages.

[zzap]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[zzap]

Overview

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

What skills do I need?

• English language

How much experience with WordPress do I need?

• Anything in between none and a lot. The best documentation is written when you do things for the first time. Also, if you don't have any experience with WordPress, then you are the best person to validate existing documentation and point to possible holes in it.

Which accounts do I need?

• WordPress.org account.
• WordPress Slack account (wordpress.org account is needed).
• GitHub account – connect your GitHub account to your WordPress.org profile.

Places where the Docs team operates:

• Blog – for meeting agendas and summaries (and anything related to the 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.

When and where are meetings happening?
Meetings happen in #docs Slack channel. Days and timing can be found in several places: The Welcome box (on the top of every page in this handbook or blog), the sidebar on the blog page, global meeting calendar.

What type of meetings does the Docs team hold?

• Regular meetings - in the form of chat in the Slack channel. These meetings are for project updates (showing off what you've been working on in documentation) and discussing any topics relevant to the team.
• Issues triage - in the form of chat in the Slack channel. These meetings are for discussing GitHub issues: assigning, re-assigning, unblocking, helping assignees etc.
• Online Contributor Days - in the form of conference calls over Zoom. These are 3 hours long, and we use them to work on GitHub issues, help new contributors get started, and discuss any problems contributors come across while working on these issues.

What contribution can I make after this onboarding session?

• Run regular meetings (including writing the meeting agenda) - role explanation, read more
• Write regular meeting summary - role explanation, examples
• Run Issues triage meetings - role explanation
• Write Issues triage summary - example
• Work on any GitHub issue you like.

How do I work with GitHub issues?
There are two major ways to work on documentation GitHub issues:

• create a new issue (you can also work on it if you want)
• work on an existing issue

When you find anything wrong with WordPress documentation (it's out of date, missing info, typo, dead link etc.), you can report it in our GitHub issue tracker by opening a new issue. At the time of writing this, we have three templates for creating a new issue. These templates will guide you on what information is needed for a good issue report.

• Fix Doc Issue Report - for reporting issues with the existing documentation page.
• New Doc Request - for proposing a new documentation page.
• HelpHub Feedback reports - for issues reported via the HelpHub feedback form.

When you want to work on existing issues, you can browse them in a few ways:

• the structured way - take a look at our project boards
• the niche way - take a look at all the labels and find your niche
• the brave way - just jump into all the issues and open the first one that looks interesting

Once you find the issue you want to work on, it is important to leave a comment in which you express interest in working on the issue ("I'd like to work on this" or something similar). This is needed because GitHub doesn't allow us to assign issues to a random username that is not in WordPress organisation. There has to be some kind of connection between the username and the issue. If the issue you like is already assigned to someone else, but the last comment is older than 3-4 weeks, you can express interest in that issue as well as lack of activity means that the issue is probably abandoned.

Show me documentation
WordPress documentation is split into two major parts:

• end-user documentation - general and block editor
• developer documentation - code reference, block editor, common APIs, themes, plugins, and advanced administration handbooks.

Team documentation is located in this handbook. Each team has their own handbook, which is maintained by the team itself.

[zzap]

Updating and creating new screenshots for WordPress end-user documentation

Recording: https://wordpress.tv/2022/03/04/update-screenshots-in-wordpress-documentation/

What do I need?

• Fresh WordPress install, the default theme and no additional plugins - WordPress Playground, InstaWP
• Screenshot tool with annotation abilities - Awesome Screen recorder and screenshot (Microsoft app, Mac App Store, Chrome extention), Nimbus screenshot (has extensions for all major browsers)

Reviewing the screenshots

When the new WordPress version is released, we want to make sure all the screenshots in the documentation match what's in the latest WordPress dashboard. Compare screenshots in the documentation article to the dashboard in the fresh WordPress install with the latest version.

Any user-facing change means we need a new screenshot:

• things are added - new buttons, text, controls, settings, etc.
• things are removed - things visible in screenshots no longer exist in the dashboard.
• things are moved - things visible in screenshots no longer exist in that place.
• things look differently - things in screenshots are in the same place in the dashboard, but they look differently (e.g., the editor background is changed due to a different default theme; icons in the toolbar are changed, etc.)

Updating existing screenshots

When creating a new screenshot, it's important to cover the same area as the existing screenshot or, if things have moved to a different place, cover the same interface.

Some screenshots are annotated. It is preferred to use the same annotation for new screenshots as well.

All screenshots should be uploaded in the comment section of the appropriate GitHub issue, after which someone will review them and update the article. Here are some examples of completed issues for updating screenshots.

Creating new screenshots

Sometimes, a feature is new, and there is no existing screenshot. Depending on the feature, showcasing it might need more than one screenshot.

When creating a new screenshot, ensure you capture enough of the surroundings to make it easier for end-users to locate it. Use annotations if necessary. Follow the order of actions in order to use the feature successfully.

All screenshots should be uploaded in the comment section of the appropriate GitHub issue, after which someone will review them and update the article.

Screenshots versus videos (GIFs)

If the feature is complex and requires a significant number of screenshots, consider recording a video demoing its usage. This video can be converted to GIF and accompanied by one or two screenshots if necessary.

Upload the video (GIF) in the comment section of the appropriate GitHub issue, after which someone will review it and update the article.