Over the last four months, I have been working on the infrastructure, processes, a page inventory, updates on existing pages and new pages for the Block editor.
There are gaps in the existing documentation with missing pages and existing pages that need to be updated as 80% of them haven’t seen an update since WordPress 5.0 came out. With constant UI changes on for every version, we need more contributors.
It’s time we expand the number of contributors!
The upcoming virtual Contributor Day at WordCamp Europe is a great occasion to bring new contributors on board. Here are some instructions and thoughts for new contributors on how to get started. Your feedback is wanted and you can share your ideas, as well as your questions in the comments below.
Hello, New contributors!
Thank you for volunteering to work on Block Editor End Documentation! My name is Birgit Pauli-Haack. My Slack username is @bph. Ping me on Slack if you have questions or ideas, either publically in the #docs channel or via private message and I will respond quickly, yet asynchronously.
Office Hours for WCEU Contributor Day is on Thursday, May 28, 2020, 15:00 UTC – on Slack in the #docs channel.
Required skill sets:
- Good English writing skills – See also the team’s collection of Writing Tips
- A content creator’s (blogger, writer) understanding for the Block Editor, no development skills are required. That’s a different team.
- Empathy for users just starting out using the Block Editor.
What tools do we use?
We use Google Drive and Slack to coordinate our work.
- If you don’t have a Slack account, stop here and create your WP Slack account.
- If you don’t have a Google Account, please go here and learn how to create one
Screenshot Capabilities
To illustrate our documentation screenshots are essentials. You would need to know how to create screenshots with your own operating system and how to convert them into image to be uploaded to your text.
Basic knowledge of Google Docs
- How to copy a document
- How to add images
- How to format text
- Sharing options for your document
Bare-bones WordPress Website
To shoot basic screenshots, you would need a self-hosted install of WordPress with the latest WordPress release (as of now 5.4.1). Many plugins add additional screen properties to the editor or your WP Admin that will confuse user, when they compare your screenshot with their own. If you can’t install WordPress on your computer, most hosting companies allow you to create sites with a temporary URL without increasing your hosting costs. Contact me, if you need assistance with this.
What about Creating Videos?
Videos are not our primary tool to help end users with the block editor. We try to explain everything in writing and with screenshots. However, sometimes it helps to just show how a certain screen option behaves in sequence to augment the written explanation. You see a few very short videos embedded into pages. It’s an enhancement and might not come into play in the first version of your documentation article. Also, the tools are not easily available and require additional skill sets.
First tasks for new contributors
The most immediate tasks is creating new pages for each Embed block of the Block editor. Here is the list in a spreadsheet.
Please select the one block you want to work on next, and enter your information into the respective columns.
- Enter your name,
- Your email address and
- Your Slack user name
- Deadline (optional)
It’s not necessary to add a date into the deadline column, although it helps to know approximately when you might find time to finish it. Don’t worry, we won’t hold your feet to the fire. Those dates are approximations, and for me, there are also a way to know when to check in with you and if everything is on track or if there are any blockers.
“If it weren’t for the last minute, nothing would get done.”
Rita Mae Brown
Are we done with the preliminaries? Let’s get documenting!
We prepared a Google Doc Sample for Embed blocks with instructions.
- Please copy the document to your Google Drive.
- Share the link to Your Google Doc in the spreadsheet.
- Start working on your first page!
As you can see it’s a bit of a set-up, but once you are through the preliminaries (Slack account, Google Account, clean install, Google Doc) you are up and running.
Three Examples: Twitter, Facebook, YouTube
We have three embed blocks already on site, their example might help you decide how deep you can go into your explanations.
When you are done with your first draft, let us know on Slack, and we’ll review it together.
Again, thank you for volunteering to work on the Block Editor End user documentation. We are thrilled to have you onboard!
If you are testing on a self-hosted site, and you can activate the Gutenberg plugin, please add also the Gutenberg 8.1 screenshots for the embed block on the bottom of the Google Doc. With the new WordPress version coming in August we will need to update your pages again to include the new UI. Add the screenshots will give us a head start on those changes.
Disclaimer: This is the first version of these onboarding instructions and you are the first contributors working this way.
Changelog
- Updated 2020-05-20
- Added a paragraph regarding Gutenberg plugin screenshot to prepare for the WordPress 5.5 changes to come in August 2020.
- Created 2020-05-18