Summary for Documentation Team Meeting February 16

 

Attendance

@drewapicture @Kenshino @desrosj @hardeeparsani @cais @milana_cap @kafleg @mrahmadawais @juhise

Change of timing

We moved the meeting forward this time due to conflicting schedules. Apologies to those who were thinking attending it at the original timing.

We are perhaps thinking of moving it up 2 hours to 2017 15:00 UTC. What do you think?

General Updates

  • Helphub is moving ahead slowly.
  • Theme Developer Handbook was released
  • DevHub comments / code suggestions clearing is going too slow (@drewapicture will help to clear)

WordPress Community Summit 2017

The community summit will be held in conjunction with WCEU this year in Paris. The last time it was held alongside WCUS in Philadelphia in 2015.

The summit will be held June 13-14, preceding WCEU, June 15-17.

The Community Summit is less like an actual contributor day and more of an opportunity to discuss and make decisions and plans for your respective teams.

Typically, for instance, you’ll see the core team make roadmap-related decisions about what’s coming up in core development for the next two years. Talk about priorities, active projects, projects you want to work on, Very much like a retreat.

The Docs team launched the Plugin Developer Handbook, for instance during the San Franciso Summit in 2014

It usually proves to be very productive for every team that meets and has a presence. It’s also an opportunity to have discussions with other teams, especially for discussing cross-team projects like helphub (docs + support + meta), devhub (docs + meta), inline docs (docs + core), etc.

People attending

@kenshino, @drewapicture

People wanting to attend

@milana_cap, @atachibana

We would love to have more people to attend from the Helphub, Theme Developer and Plugin Developer Handbooks teams. If you are working on a documentation project for WordPress.org, or if you’re a documentation junky who wants to contribute, please let @Kenshino or @drewapicture know that you’re interested.

Attendance to the WordPress Community Summit is through nomination by the Make / WordPress team leads. We can only nominate you if you let us know you’re interested!

We will have to submit this by the end of February. Please let us know by then!

Summit Discussion Topics 

  • Game plan for recruitment
  • Onboarding Plan
    • We get a ton of people wanting to contribute but we have no established recourse for providing that access.
  • State of Doc’s Team (own) documentation
  • DevHub and Helphub translation Mechanism (Docs + Meta + Polyglots)

We would love to cover more in the summit, so please post topic suggestions in the comments!

WP CLI Code/Command Reference

We’ll probably be restarting devhub meetings soon, so for now, I’d say just leave the command docs in control of wp-cli.org and we’ll look at short-term and long-term solutions to bringing those docs over.

The upside of wp-cli command docs is that they’re already written in PHP and use phpdoc to parse into the staticly-generated pages, so we might be able to fork the parser we use for the code reference.

Read the meeting transcript in the Slack archives. (A Slack account is required)

#summary

Theme Developer Handbook released

After around close to 2 years of development, through a total of 3 different teams, we have released the Theme Developer handbook, thereby completing the Developer Hub’s goal of having proper developer docs for the main aspects of WordPress.

This could not have happened without a few of the initial leads and project pushers – @siobhan, @samuelsidler @sewmyheadon @lizkaraffa @thoronas @jcastaneda @grapplerulrich @anthonynotes @topher1kenobe.

The list of people involved (not yet complete) is documented here and last count puts us at close to 100 people involved in the handbook in one way or another.

The handbook has been released in it’s version 1 form and is updated all the way to 4.7.

There’s always more to do and the team continues to manage and improve the handbook on Trello.

Please do give us feedback using the methods detailed here.

We hope this helps everyone make better themes!

Get cracking at https://developer.wordpress.org/themes/

Props to the editors who came in after the handbook progress stalled for awhile @kenyasullivan @xfrontend @burlesonbrad @nao @jacobmc @hardeepasrani @sheebaabraham @boogawooga @rahulsprajapati @viniciuslourenco @kafleg @atachibana @sarahovenall @sushil-adhikari @celloexpressions @juhise

+make.wordpress.org/themes

Agenda for Helphub meeting December 13

Hello!

We have missed a few meetings due to holidays and WCUS. Let’s get one or two in before Christmas and the New Year hits us again!

Time/date: Tuesday, December 13, 2016, 14:00 UTC in #docs

  1. Attendance
  2. Migration Updates
  3. Design Updates
  4. Development Updates
  5. AOB

Pinging @atachibana @jon_bossenger @karys @nlarnold1 @greensteph @sarassassin @bethannon1 @juhise @hlashbrooke @sergeybiryukov @bravokeyl @quitevisible @ankitguptaindia @anevins @justingreerbbi @carlalberto @geoffreyshilling @normalize @hardeepasrani @danhgilmore @wizzard_ @cristiano.zanca @tacoverdo @lumberhack @krogsgard @clorith

If I have missed any usernames, it’s not on purpose and do consider yourself invited to the meeting.

#agenda

Volunteers needed for Theme Developer Handbook

Hello fellow Doc-lovers,

As you may know, DevHub has already been up for awhile and large strides have been made by @drew to get all portions of DevHub up and running.

Recently, I took over the management of the Theme Handbook project and I believe we’re about 80% done. (was 90% but we’ve had a few major releases since then)

Thanks to @lizkaraffa & @thoronas for leading the team thus far!

There are a 2 major areas (blockers) that will need to be finished before we can do an initial release of THB.

  1. Clearing the To-Do list located at https://trello.com/b/sBXllyQT/theme-developer-handbook
  2. Updating specific articles to reflect recent core changes such as adding ‘Custom Logos’ under core supported features

The beta form is currently at https://developer.wordpress.org/themes/getting-started/

We need you, doc lovers & previous contributors to the Theme Handbook to help us get this to the ‘release-able’ stage.

We are currently managing the project on our Trello Board

If you’re interested to help, please ping me @Kenshino on #docs, Slack or simply comment here!

#theme-developer-handbook

Docs-focused Bug Scrub Friday

We’ll have a docs-focused bug scrub Friday, Oct. 7 2016 14:00 CDT in the #docs Slack channel, for anyone interested in contributing. We’ll focus on the needs-docs keyword first, then on the docs focus if there’s time.

#4-7, #inline-docs

Summary for Helphub Meeting 12 July

Attendance

@atachibana @carlalberto @greensteph @sarassassin @bethannon1 @juhise @normalize @geoffreyshilling @karys @justingreerbbi @adamsilverstein @Kenshino attended

Migration Updates

@geoffreyshilling @juhise @normalize reports that they are actively migrating articles. @atachibana will be finishing up his portion of the migration and will head towards migrating the WordPress Version articles

If migrators see any theme function related articles, they should do the following

  1. Leave a short explanation on the subject matter
  2. Leave a link towards the theme handbook on Devhub eg. https://developer.wordpress.org/themes/functionality/sidebars/

@Kenshino reminded all migrators to replace Codex links with Devhub links (when applicable).

Design Updates

@greensteph has partially finished the single view of the WP Versions Custom Post Type. It looks great and she’ll be continuing her work here https://wp-commhub.mybalsamiq.com/projects/helphub/WordPress%20Versions

It was suggested to strip the empty headings off the single article view so the article could concisely show what was changed.

@Kenshino suggested that stripping made sense, however, creating a section that lists Components that were not updated would be more inclusive.

@adamsilverstein enlightened us how the WP Versions (current) Codex articles are created. This will surely help to drive design decisions.

Development Updates

The WordPress Versions CPT was created and added onto wphelphub.com.

wphelphub.com was updated with the fixed versions of Helphub Post Type and Read Time. So migrators should stop seeing any warnings/notices that makes migration hard.

@carlalberto and @Kenshino will be working on the templates and styles for WordPress Version archive and single pages.

Codex Translations – how can we be inclusive?

Redirecting the English articles effectively makes any translate Codex articles tough to find.

A provisional decision was made to put a deprecated notice on the English articles for users to be manually directed to the new Helphub articles. This will give time for the translation editors to find a best solution for their community.

After a given amount of time, the auto redirection will be put in.

Read the meeting transcript in the Slack archives. (A Slack account is required)

#summary

Codex Migration project update

History

When the docs team embarked on the Codex Migration project at the WCEU contributor day in June 2015, it seemed like a daunting, never-ending task.

The goal was simple: move away from using the Codex as the canonical reference for developer docs to a newly-established “Developer Hub”. The bulk of the documentation would be parsed from the WordPress source and be supplemented with some manually curated documentation along with user-contributed notes (examples).

There were a lot of reasons for why the Codex migration project was launched, the most prominent being that the Codex had reach an un-maintainable state as a manually curated community reference. Now a year later, we’re well on our way toward completely migrating all function references from the Codex to the Code Reference.

Side note: The HelpHub project also falls under “Codex Migration”, but more on the user and support docs end of the spectrum. Check out the HelpHub project page for information on contributing that effort.

Examples Migration

It all started with the examples.

Over the last year, 15 or so contributors manually migrated more than 1,100 function examples to the Code Reference and submitted them to the moderation queue as user-contributed notes.

Before approval, each example was individually evaluated for accuracy, completeness, and security by about 10 trusted reviewers from throughout the community. I approved the last of the migrated examples just a few weeks ago.

Content Migration and Redirection

With mixed feedback from the community, we’ve started the long process of redirecting the more than 1,200 function references from the Codex. Like the examples, each redirection is happening manually; there’s no automation here.

Great care is being taken to ensure that any useful (and accurate) information in the Codex makes the move too, either through direct improvements to the inline docs or by being brought over to the “More Information” section of each reference page.

Side note: we’re already seeing some of the “More Information” sections getting to be pretty long in some cases, and are looking into implementing some in-page navigation to make discovery a little easier.

Thank You Contributors

At this point, I’d like to send out thanks go to all of our contributors so far: @adamsilverstein, @atachibana, @bford2here, @bhlarsen, @boogawooga, @cmmarslender, @DBrumbaugh10Up, @hearvox, @helen, @ishulev, @marcomartins, @mcadwell, @morganestes, @mrsipstenu, @ninnypants, @rabmalin, @stevegrunwell, @sudar, @theMikeD, @tott, @vlastuin, @webdevmattcrom, @znowebdev

Special thanks also go of course to @samuelsidler and @siobhan for their steadfast support in getting this project off the ground in the first place, and to @coffee2code for managing the bulk of the infrastructure, special requests, and development of features in getting us this far.

We Need Your Help

According to the progress graph, approximately 160 function references have already been migrated and redirected. There are another ~900 still to be moved. If we follow a strict regimen of migrating at least 10 references a day for the next 3 months we should be able to complete the function reference section of the Codex Migration project. Of course that still leaves class and hook references, but one thing at a time 😅

It’s doable, but I probably shouldn’t try to do it all myself without a little bit of help. If you’re reading this and thinking, “Boy, I think I can help with this,” pipe up in the comments below or ping me on Slack at @drew in the #docs channel.

We’re over the hump, but there’s a long way to go. More frequent status updates will follow.

#codex-migration, #examples

Codex to HelpHub Migrator Tool in Beta

As Drew wrote in the below post, we are migrating Codex articles to HelpHub documents by hand work. Technically, it means converting Wiki formatted article to WordPress/HTML formatted article.

Codex:

==Title==
This is example article.
* List1
* List2

HelpHub:

<h2>Title</h2>
<p>This is example article.</p>
<ul>
<li>List1</li>
<li>List2</li>
</ul>

This is a repetition of dull acts especially when the volume is huge. To eliminate such tasks and use our effort to more essential things such as brushing up documents, I created migrator aid tool.

http://unofficialtokyo.com/codex-converter

Usage is simple. Cut & paste the Codex Article in the left box and click button. Not only above conversions, notation of “[[codex_title]]” will be converted to the appropriate HTML link

Codex:

[[Administration Screens]]

HelpHub:

<p><a href="https://codex.wordpress.org/Administration Screens">Administration Screens</a></p>

I hope it will reduce the migrator’s cost and boost our journey to the HelpHub. Any comments are welcome.

Re-re-starting weekly Docs chats

Yep, we’re really doing it this time! Starting Thursday, June 30, 2016 17:00 UTC, we’ll be restarting weekly Docs chats.

The docs team has kind of floundered for a long time now in terms of not having weekly chats and generally failing to onboard new docs contributors. Let’s get this thing going again.

After speaking with @kenshino (who has awesomely taken on stewardship of the HelpHub and Theme Developer Handbook projects), I’ve adjusted the weekly meeting times back an hour to 17:00 UTC.

As usual we’ll be meeting in the #docs channel on Slack.

Check out the Weekly Meetings list in the sidebar for more information on the various docs-related chats happening on a weekly basis.

HelpHub: Management change

Hey folks,

For the past few weeks regulars on the HelpHub team may have noticed that I have been somewhat more absent then previously. The primary reason for this is that I have recently joined the Community team full time (both as part of my work at Automattic, and also as an active member of the WP community). This is a big change in terms of the work that I’m doing on a daily basis, and one of the main effects of the change is that my time spent on WP projects will, for the time being, be primarily focussed on the Community team. The upshot of this is that, at risk of spreading myself too thin and not doing the project justice, I will be stepping down from managing the HelpHub project.

To be honest, this won’t affect things too much as those of you working on the project each week are doing such a sterling job that the work there is moving along very well already. In my stead, the very able @kenshino has stepped up to manage the project (as his posts on this blog show quite clearly). He was already helping me out a whole lot before this change, so he was the obvious choice really 🙂

I will still be on HelpHub team and will contribute where I can, but my role will no longer be an oversight or management one. I will attend the meetings when I can and will throw in some contributions where I am able to do so, but @kenshino will be handling the organisation of things going forward.

HelpHub meetings are still at the same time each week – Tuesdays at 14:00 UTC in #docs – so for those who already regular contributors, or others who would like to get involved in the project, please don’t hesitate to stop by those meetings and get involved in what is a very exciting project.