Call for Feedback on Tone and Voice Guide

Hello everyone,

With the guidance of @atachibana and @kenshino, I’ve written a draft for a guide to tone and voice in WordPress. It can be found here.

It covers the overarching voice of WordPress as well as the specific tones to use when writing user and developer documentation.

I’m not sure whether the distinction between tones for user and developer documentation is clear at this stage, so any feedback there is welcome.

Otherwise, don’t hesitate to give any general feedback and any suggestions for other types of documentation you’d like to see covered in the guide.

Thanks! 🙂

Agenda for HelpHub meeting 17 December 2018

Hello all,

Next HelpHub meeting will happen on

Monday, December 17, 2018, 15:00 UTC

This is the last meeting we’re going to have in 2018 so I’ll be attempting to cover quite a bit

  1. Attendance
  2. Phase 1 Launch
  3. Phase 2 discussion
  4. HelpHub contents
    • Content Migration Check-in
    • Writing Style
    • Maintaining Classic Editor & Block editor docs
  5. AOB

Helpful Links

  • HelpHub Staging – https://wp-helphub.com/
  • GitHub repo – https://github.com/kenshino/helphub
  • State of HelpHub (read for Phase 2) – https://make.wordpress.org/docs/2018/02/26/state-of-helphub-february-2018/
  • Last Docs’ Team meeting notes – https://make.wordpress.org/docs/2018/12/17/summary-for-docs-team-meeting-17-december-2018/

Agenda for Docs Team Meeting 7 January 2019

Happy New Year!
Our first Doumentation Team meeting in 2019 is scheduled on

Monday, January 7, 2019, 15:00 UTC

in the #docs channel on Slack

Current Projects Updates:

  1. Codex Migration (DevHub) – @atachibana
  2. DevHub – @drewapicture & @coffee2code
  3. HelpHub – @kenshino
  4. Inline Docs – @drewapicture & @atimmer
  5. Gutenberg Handbook – @chrisvanpatten

Open Floor

Feel free to comment if you have items to add to the agenda.

Gutenberg Dev Docs: Call for Contributions

With the release of WordPress 5.0 and the new Gutenberg block editor, there are many changes in WordPress for users and developers alike.

For developers in particular, the changes are dramatic. As such, we also have a lot of new documentation to create: and we need your help!

If you’re a developer and have spent time working with Gutenberg, this is your time to shine. We’re looking for contributions in a few specific areas.

Examples

Most of the requests we get are “how do I do X?”, so we are looking for code examples and “micro-tutorials” that can help developers solve these questions and integrate with Gutenberg.

Contributions here are ideally in the form of a single markdown file, with at least a few hundred words that describe the problem and walk users through the solution, with complete code examples. They should link out to the relevant API documentation (where it exists) or to other areas of the handbook that offer further context.

A few ideas for contributions include…

  • How to register a sidebar plugin
  • How you might use InnerBlocks
  • How you could port a custom metabox to a custom sidebar plugin
  • How to trigger a modal
  • How to write block attributes to post_meta
  • How to use the color HOCs and components in your blocks
  • How to filter specific areas of the editor (especially panels in the document settings sidebar)
  • How to filter the available blocks in the editor
  • How to use the data module to retrieve post data within a custom component

Package documentation

Gutenberg is built with a collection of npm packages. Some of these packages have great documentation in their READMEs, but others don’t. This is another great way to contribute: choose a package, and improve the README in a pull request on the GitHub repo.

Each README should include:

  1. Installation instructions (most have this already!)
  2. General/basic usage instructions
  3. Function documentation, if applicable
  4. Links to other documentation that might be relevant/helpful

Component documentation

The new editor also leverages Components to build the user interface. These are provided inside the @wordpress/components package. Each component should have its own README that contains:

  1. Basic usage example
  2. “Dos and Don’ts” of how to use the component correctly (from a UX perspective)
  3. Attribute documentation

This GitHub gist is a template that you can use as the basis for your own component documentation.

Other options

Although these are our highest priority items, they are by no means the only ways you can contribute. The “Documentation” label on GitHub offers many more ideas. Picking a ticket and writing the documentation to solve the issue is a great way to contribute.

We’re all committed to making Gutenberg documentation the best on the web. Thanks so much for your interest, and we hope you’ll also consider joining our weekly meeting in #docs in Slack at 18:00 UTC!

Summary for Docs Team meeting 17 December 2018

Attendance

@kenshino @milana_cap @atachibana @michelebutcher-jones @softservenet @felipeelia @abrightclearweb @chrisvanpatten @joyously @daveryan attended

Codex Migration (DevHub)

This is still on halt as efforts are still on HelpHub to deal with the launch that happened in early December.

The same content contributors are now moving in sync towards the project that requires immediate attention.

HelpHub

The project did a soft launch on 1 December 2018 to ensure that Gutenberg Docs would have a permanent spot to stay in when WordPress 5.0 launches.

HelpHub’s home page

It has been raised that HelpHub’s home page is too strikingly similar in design to the forums’ homepage. (i.e. WordPress.org/support and WordPress.org/support/forums)

After a small discussion, it’s been suggested that this to be raised with the support team to see if they feel the same.

@joyously has been asked to assist with this.

Content Migration

The content readiness check of Phase 1’s content migration (113 of the top pages of Codex) is almost done and will be finished before the next meeting.

This effort is detailed at https://docs.google.com/spreadsheets/d/1PeHj7pSFLcdMbIC41JJdzEkl12TJT3mwWyzQv2mi01U/edit#gid=835534324

Blog Post & Future Plans

@kenshino is working on a blog post to be posted on WordPress.org’s News page and a separate more detailed writeup on Make / Docs

  1. General direction and explanation of HelpHub which would be great for end users (on WordPress.org)
  2. Actual plans and details e.g. how we’re looking to handle translations etc (on Make.WordPress.org)

Gutenberg Docs

@daveryan and @chrisvanpatten are consolidating materials generated at the Contributor day of WCUS and will present updated plans for Gutenberg docs.

This was later posted here – https://make.wordpress.org/docs/2018/12/11/gutenberg-dev-docs-call-for-contributions/

It does bring to the question as well on how we’d retain docs that pertain to before and after 5.0

@abrightclearweb also asked about definitive names to describe different areas of Gutenberg. This is something that wasn’t solidified yet at meeting time and will require documenting before useful help articles can be written consistently.

E.g. Writing a blog post would be a very different HelpHub article for 4.9 and 5.0

WCUS

@softservenet and @wizzard_ represented us on WCUS and their experience is detailed here – https://make.wordpress.org/docs/2018/12/16/wcus-2018-highlights-contributor-day/

We didn’t manage to get to talk about DevHub or Inline Docs effort because the key project leads were travelling out after WCUS.

If you would like to read the meeting in full via Slack logs, it’s here – https://wordpress.slack.com/archives/C02RP4WU5/p1544454025327600

Summary of HelpHub meeting 03 December 2018

Attendance

@kenshino @atachibana @sergey @mapk @milana_cap @felipeelia @pbiron @abrightclearweb @mkaz @hlashbrooke @clorith @chrisvanpatten

Phase 1 Launch

Phase 1 was softly launched at wordpress.org/support. It was featured in Hugh’s post The Month in WordPress: November 2018 and, thanks to @drewapicture and @mapk, will be mentioned in Matt Mullenweg’s State of the Word at WordCamp US coming up this weekend. For State of the Word’s slides (made by @mapk) @atachibana prepared Phase 1 statistics and list of content contributors, while the list of development contributors is prepared by @milana_cap.

Search functionality on wordpress.org/support doesn’t include new HelpHub articles while it does the old Codex ones – track ticket. This is a big problem and we need to, first and foremost, include HelpHub in search and find a healthy way for smooth shutting down the relevant Codex pages. It was proposed to turn Codex to read-only state, improve the notice to clearly state where new information can be found and then redirect relevant Codex pages to HelpHub ones as Codex is pretty good indexed.

On a matter of naming it’s been decided that we’ll keep HelpHub as a project code name while official name will be “User Docs“. It will stand next to “Forums” and “Developer Docs” in main menu for wordpress.org/support.

All issues for Phase 1 will move to track while for Phase 2 remain on Github. To create new ticket go here: https://meta.trac.wordpress.org/newticket and select “Support Hub” component.

Phase 2

@mapk started with mapping Gutenberg blocks for publishing HelpHub content – github issue. Here’s the demo: https://wpuxtesting.com/2018/11/version-4-9/

Transcript of meeting can be found here: https://wordpress.slack.com/archives/C02RP4WU5/p1543849346079100

#summary

WordCamp US Contributors Day – input needed!

As most of you probably know, it’s nearly time for WordCamp US again. And with that also comes a Contributors Day! For this day Tom Ford and me will be leading the Documentation table. We want to have something to of course, and for that, we need your help!

Our main objective right now would be to find different topics that would fit into these two sections:

  • Something for experienced contributors to do.
  • Something suitable for newcomers that can easily be learned or picked up.

I’d like input from all of you (preferably on both subjects) with stuff we can do during that day. A soft deadline for that would be in 7 days, on December 5th. I’ll be gone traveling towards Nashville from then on, so I won’t be able to discuss or ask questions easily for a couple of days. A hard deadline would be on the morning of the actual Contributors Day.

Hopefully, you can come up with some interesting subjects.

Agenda for HelpHub meeting 3 December 2018

Hello all,

Next HelpHub meeting will happen on

Monday, December 3, 2018, 15:00 UTC

We did a quiet soft launch of Phase 1 over the weekend. So this meeting is gonna focus about how we should be stabilishing Phase 1.

  1. Attendance
  2. Phase 1 Launch
  3. Phase 2 discussion
  4. WCUS Contributor Day
  5. AOB

Helpful Links

  • HelpHub Staging – https://wp-helphub.com/
  • GitHub repo – https://github.com/kenshino/helphub
  • State of HelpHub (read for Phase 2) – https://make.wordpress.org/docs/2018/02/26/state-of-helphub-february-2018/

Call for Volunteers – HelpHub Migration

Hello!

As you might know from our meeting updates – HelpHub has taken awhile to finally materialise. One of the hurdles was working out a migration plan. Unfortunately, because of WordPress.org’s unique setup, we were not able to get things automated or even use WordPress’ import mechanisms.

This means that we actually need to specifically do manual migrations from the Staging site – wp-helphub.com to the Production spot WordPress.org/support

How are we doing it?

Specifically – we are doing the following

  1. Use the Copy All Content function of the Gutenberg editor on an article on the Staging site
  2. Paste it the content onto the Production site
  3. Do the same for the title and check the correct taxonomies
  4. In the case that it’s still using a Classic block, we’ll have to switch it to Gutenberg blocks
  5. Ensure that all media used (pdfs, images etc) are downloaded and re-uploaded back to WordPress.org/support
  6. Check it for irregularities
  7. Save the draft

You might be able to appreciate that it is a pretty tedious process. By the time you read this post, we should be up to 30 of 170 articles completed. Another 140 articles is a lot to migrate for a team of 5.

Why the rush?

We want HelpHub to be ready for the Gutenberg team to drop in their user documentation. Given that WordPress 5.0 is designated to ship November 19, we don’t have a lot of time left.

We don’t want to leave users in the cold. And you could help us.

What can I do?

If you have some copy pasting skills, a keen eye for detail and an hour free over the next 2 weeks; you can help us!

Drop @atachibana (who’s the Content Lead) a line with your wordpress.org account and registered e-mail address. He will sort you out with the correct access and the know how.

If you have any questions, just ask in #docs on Slack.

Reference

P.S. If you received this call of volunteers earlier, we accidentally published it earlier!

Agenda for Docs Team meeting 29 October 2018

The next Documentation Team meeting is scheduled on

Monday, October 29, 2018, 15:00 UTC

in the #docs channel on Slack.

If we do not get any attendance, open floor will be held instead

Current Projects Updates:

  1. Codex Migration (DevHub) – @atachibana
  2. DevHub – @drewapicture & @coffee2code
  3. HelpHub – @kenshino
  4. Inline Docs – @drewapicture & @atimmer
  5. Gutenberg Handbook – @chrisvanpatten

Documentation Team’s handbook

  • We’ll check on the progress of Docs Team’s handbook improvements

Open Floor

Feel free to comment if you have items to add to the agenda.