Summary for HelpHub Meeting 26 August 2019

Attendance

@estelaris @kafleg @FahimMurshed @wizzard_ @softservenet @ibdz @felipeloureirosantos @justin @bph @kenshino @felipeelia @milana_cap @samikeijonen

Development

We discussed several issues today.

Excerpts on Archives

Last year it was proposed to replace auto generated excerpts with ToC list items. On today’s meeting discussion it’s been decided to use manually created excerpts which would contain the point of the article in one sentence. Short and concise. more meaning, less space.

Join discussion here: https://github.com/WordPress/HelpHub/issues/239

Posts Order on Archives

This was unsolved for a long time. We decided it’s important to order posts according to its content complexity so it resembles “Step 1, Step 2..” format or, if this doesn’t apply, to order according to post’s “importance”. As this is difficult to apply automatically to all categories we decided to use Post Attributes order and intentionally create order which we will specify in WP_Query.

As some articles have more than one category assigned, in which it might have different “importance” and order, we decided to make larger steps between posts using the same logic as menu items in dashboard. So two posts in a succession would have 10 places in between, rather than 1. This should also help with ordering articles published in the future.

Join discussion here: https://github.com/WordPress/HelpHub/issues/237

Single article mobile view

Viewing single article on smaller devices reveals the sidebar throughout the whole visible area. The rest of Handbooks solve this by hiding the sidebar altogether. @milana_cap suggested to place search form and single posts navigation instead of sidebar. For this single posts navigation to be useful, the order of posts (above) should be logical and intuitive.

@estelaris said that she’s working on templates and will discuss this issue on #design team meeting this Wednesday, as this is effecting all WordPress.org Handbooks.

Join discussion here: https://github.com/WordPress/HelpHub/issues/236

Design

@estelaris is working on overview of HelpHub design. Her analysis can be found in Google Spreadsheet: https://docs.google.com/spreadsheets/d/1ZnhtiLxqjXviFlnWsDE5L8YRiBXtkmanvM8doIc1lrg/edit?usp=sharing

After we agree on design template we need to have #accessibility review and usability test. @samikeijonen kindly accepted to perform these testings once we have everything ready.

Content and Rosetta Releases

We skipped these due to absence of key people.


Next Docs meeting is in #docs channel on

Monday, September 02, 2019, 15:00 UTC

You can take a look at the meeting transcript via this link: https://wordpress.slack.com/archives/C02RP4WU5/p1566831612366600

Summary for Docs Team Meeting 12 August 2019

Attendance

@kenshino @milana_cap @atachibana @clorith @David Curtiss @bph @leogermani @juliobox @softservenet @audrasjb @chrisvanpatten @clorith

Development

We are waiting for @netweb to finish setting up SVN and GIT repos together. Meanwhile @milana_cap started working on https://github.com/WordPress/HelpHub/issues/214 Once the new workflow is completed regular bug scrubs will be scheduled again.

Mobile view of HelpHub is identified as making HelpHub hard to use so we are going to prioritize those fixes if we don’t get the git + svn work done by this week.

Content

There are no requests for new pieces that we need to write. @atachibana volunteered to follow the state of Block Editor user’s docs as it is still hard to be found by people. @bph volunteered to help. They will reach out to @karmatosed regarding improvements.

We would like to have some input from Support Team on obvious gaps for Block Editor Docs. @clorith will bring this up on their next meeting.

@leogermani did half of remaining redirects and updated the spreadheet, expecting to finish everything by the end of the week. @audrasjb volunteered to help, @juliobox is already on it.

Design

Skipped due to missing reps.

Rosetta Releases

Japaneese release gathered 11 volunteers. Serbian rosetta still doesn’t have HelpHub enabled. @kenshino will ping @sergey about this.

Open Floor

We currently have 288 user notes (DevHub comments) in queue. @audrasjb volunteered to help with reviews. @softservenet will start a spreadsheet of Docs Team’s ongoing tasks and members working on them. 

Next Docs meeting is in #docs channel on

Monday, August 19, 2019, 15:00 UTC

You can take a look at the meeting transcript via this link: https://wordpress.slack.com/archives/C02RP4WU5/p1565622003178300

#docs

Summary for Docs Team Meeting 1 April 2019

Attendance

@milana_cap @nosolosw @joyously @chrisvanpatten @kafleg @makewebbetter @aduth @jankimoradiya @immeet94 @kenshino attended

HelpHub Development

We’re currently trying to move issues form GitHub to Meta Trac to give proper visibility over bugs that affect the code base that was merged into WordPress.org

The team is working on checking if the issues are reproducible on WordPress.org and will migrate related issues.

@milana_cap has updated the list of developers that contributed code to HelpHub. We’re working out which badge to give (Meta or Doc) and will finalise this soon

@milana_cap and @clorith are working on a monthly bug scrub date/time

HelpHub Design

It’s been raised that the forum and HelpHub landing pages are too similar. A discussion will be needed with @iviolini and @clorith to work this through

Gutenberg Handbook

@nosolosw mentioned that the Gutenberg docs have improved quite a bit thanks to the efforts of many people, and the main issue now is discoverability

It was recommended by both @Kenshino and @chrisvanpatten to get the contents of the current Gutenberg developer documentation into a DevHub handbook as a main focus and work out both the technical roadmap and the content re-ordering at a later stage.

@nosolosw will be conferring with the Gutenberg team over the next few days.

Google Season of Docs

In short – there’s 3 months that a technical writer (or more) that can sign up to write docs for WordPress.org

We could decide where the focus should be. It could be working on improving Gutenberg Docs or making sure we look at the other handbooks to review the level of technical writing that we’re at

@chanthaboune is looking into how we’d apply as WordPress.org and mentors are needed for this effort. If you’re interested, take a look at https://developers.google.com/season-of-docs/docs/mentor-guide and let us know you’re interested either via DM on Slack, a message in #docs or a comment on this P2 post!

Documentation Team Badges

After a bit of discussion, we’ve landed at a criteria

  • Documentation Contributor: You have contributed over X number of changes across HelpHub or DevHub.
  • Documentation Team: You regularly attend Documentation Team meetings and you are either a project lead or a team lead of a project.

Contributor badges are likely to be permanent and Team badges denote current activity over a period of 2 months.

We’ll likely have to work on the criteria a little more and will make a separate P2 post to solicit feedback before confirming it.

Maintenance of Theme Developer Handbook

The Docs Team would like to bring in the Theme Review Team to take ownership of the Theme Review Handbook (just as Plugins has done so for the plugins handbook).

@kafleg has been requested to form a team and work with @atachibana to bring the theme handbook up to speed.

You can read a transcript of the meeting via https://wordpress.slack.com/archives/C02RP4WU5/p1554130866012100

Agenda for Docs Team Meeting 18 March 2019

Our next Documentation Team meeting is scheduled on

Monday, March 18, 2019, 15:00 UTC

in the #docs channel on Slack

Current Projects Updates:

  1. Content Migration from Codex to HelpHub & DevHub – @atachibana
  2. HelpHub development – @milana_cap
  3. Inline Docs – @drewapicture and @atimmer
  4. Gutenberg Handbook – @dryanpress @chrisvanpatten and @nosolosw

    Now we have “Block Editor” icon on the DevHub main page: https://developer.wordpress.org/
    But, the plan of moving contents is not clear from previous discussion. Can anyone explain it in the meeting or on #docs?

Open Floor

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

Summary for HelpHub Team Meeting 11 February 2019

Attendees: @kenshino @atachibana @moghillfifi @milana_cap @moghillpat @kafleg @marioernestoms @atachibana @williampatton

Contents Migration

@atachibana Submitted Report on Migration

  • 26 of 53 completed (49%) mainly by @Pixelateddwarf
  • Version Text 77 of 349 completed (22%) mainly by subrataemfluence, 107 in progress (31%)
  • If anyone has interests in these activities, please read this document or contact @atachibana https://make.wordpress.org/docs/handbook/helphub/migrating-articles/

Development for Phase 1.5

@milana_cap submitted the updates
First, all the issues are labelled as,
Phase 1.5: https://github.com/Kenshino/HelpHub/issues?q=is%3Aissue+is%3Aopen+label%3A%22Phase+1.5%22
or
Phase 2: https://github.com/Kenshino/HelpHub/issues?q=is%3Aissue+is%3Aopen+label%3A%22Phase+2%22

She is thinking of moving Phase 1.5 issues directly to Meta Trac.
@milana_cap will work on immediate fixes for the blockers now and will coordinate with @netweb to work out next steps.

Design

@iviolini has taken over from @mapk as Design Lead for HelpHub.

There are issues labeled with Design tags on GitHub that will require @iviolini to review.

Content Migration check-in

@atachibana explain the updates about this. There are 3 or 4 active members. For Phase 1.5 completion, the numbers might be enough.

@moghillfifi and @Moghillpat have volunteered to help with editing/proofreading.

WordCamp Contributors Day and Contribution

@milana_cap Will be at WC Nordic CD, they’ll have docs team and she will try to gather more volunteers for the Docs team. @kenshino will be on WC Bangkok and will work to get more volunteers.

Voice & Tone guide

@kadair updated it after all the comments received in https://make.wordpress.org/docs/2019/01/16/call-for-feedback-on-tone-and-voice-guide/
@kenshino will make a blog post and say that we’ve gotten a consensus on this and we’re publishing it as the official WordPress tone and voice guide – it’s still open to improvements of course (as with anything in WordPress)

HelpHub localisation plan

@nao and @kenshino worked on it. https://docs.google.com/document/d/1d5a64LN564zB-HrxvRr9u1zKepD5yaVYb-cL02r5euQ/edit?ts=5c47e862
@moghillfifi will give it a proper read through before we go on publishing. We will probably publish it on mid week.

You can join #docs channel on Slack for the more updates.

You can check out Slack for meeting logs – https://wordpress.slack.com/archives/C02RP4WU5/p1549897229001500

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 of Gutenberg docs meeting 24 October 2018

Thanks to everyone who joined us for the kick-off Gutenberg docs meeting!

Below is a summary of last week’s meeting.

  1. Opened with introductions and hellos, and a description of @chrisvanpatten‘s goals for the group
  2. Set future meetings for 1pm ET/17:00 UTC on Tuesdays, in #docs on Slack
  3. Discussion of where documentation would “live”
  4. Goal is to continue allowing docs to be prepared in GitHub
  5. @drewapicture raised some questions about what the Gutenberg handbook represents, suggesting it not exist as a mono-doc when merged into core
  6. @kenshino raised the idea of splitting into separate handbooks: auto-parsed documentation in DevHub, developer handbook in DevHub, and user handbook in HelpHub
  7. (@chrisvanpatten also added a contributor handbook to be considered too, likely to live on GitHub for now)
  8. Established next steps:
  9. Lock down high level documentation outline
  10. Open a PR to reorganise the documentation
  11. Determine list of holes in documentation
  12. Begin assigning writing tasks in GitHub issues/high level project/milestone
  13. Established next meeting for Tuesday, 30 October at 1pm ET/17:00 UTC in #docs
  14. </meeting>

I’ll post an agenda for our next meeting tomorrow a few hours before the meeting. Thank you everyone who joined us!

State of HelpHub February 2018

What is HelpHub?

Project HelpHub is the user documentation base that will sit on WordPress.org/support. It's the companion to Developer's Hub which serves development documentation.

The general guiding philosophy for the design, content creation, and build of the project is – Help users help themselves.

We want users to be able to find answers on WordPress.org before posting on the forums. We want to make documentation more discoverable, through enabling search, visual improvements and concise targeted content.

We've been working on HelpHub for some time now and its possibly the final item that needs completion from the roadmap created by the Docs Team way back in 2013.

What’s the difference?

The biggest change is actually using WordPress to power content!

Shifting away from Codex was a deliberate decision

Scribbles the Docs Team did in 2013, suffice to say Codex wasn't enough

  • Too many pages that deal with the same issue (we have 4 getting started pages!)
  • Conflation of user and developer content
  • Content is hard to navigate
  • Content is way way way way way too verbose
  • Too much irrelevant content
  • Codex couldn't be realistically improved in it's functionality to deliver meaningful content

HelpHub aims to curate articles in a more concise way with standardised formatting and screenshots where possible.

Proper editing via WordPress back end & Gutenberg

The possibility to add functionality as need arises

Adding read time to help keep articles concise

Current State

We want to release a minimum viable product, and we have classified it as such below:

MVP – Plenty better than Codex

  • Better content
  • Internal search
  • Improved readability through design and content re-writes
  • Better article discovery through better categorisation
  • REST API endpoints

Phase 2 & beyond – Iteration

Phase 2 & beyond will have the team working on the enhancements on top of the basic features. We'll keep iterating to make things more use-able, easier for people to collaborate and of course create better content.

Examples are

  • WordPress Search -> ElasticSearch
  • Simple input search -> Auto complete and Suggestions via JS
  • And more

We'll also work on new features based on understanding how well the basic ones work and what the general end public needs next. Such could be article voting, direct article contribution via Feedback or user guides for example.

Team

Many people came in to help, unfortunately, life happens. We will need some consistent help going forward.

It is also plainly obvious that having an overall project lead isn’t enough to help tackle the pre-launch needs, let alone the post launch ones.

They have already been doing these tasks but it would be great to properly introduce them

Release Date

Our focus right now is to complete the development work for MVP and also work with the Meta and Support Team to properly setup HelpHub on WordPress.org

We aim to release HelpHub latest by 31st May 2018. We are working however to release it earlier than that.

Progress of Phase 1 (MVP)

  • Articles are appropriately categorised
  • Many popular articles were re-written
  • General WordPress.org styling are being merged in

We're now focusing on the tasks needed to ensure proper integration to be the Hub Page of WordPress.org/support

What do we need?

Developers. Consistent developers who are familiar with WordPress & PHP coding standards and good practices.

Content Migrators and Editors who are familiar with editing in WordPress.

If you would like to join us, you can do so in the following ways

  1. Comment here
  2. Join us at HelpHub meetings Tuesdays at 15:00 UTC in #docs
  3. Ping @clorith or @zzap for development, @atachibana for content on Make WordPress Slack

Take a look

We have the the staging version of the site up. (It still requires a fair bit of styling fix but the fundamental code to run it is in). It's not the prettiest right now but we're working on it. And we could certainly use your help!.

See it in action here – https://wp-helphub.com/

Project Documents & Links

  • Github Repository: https://github.com/kenshino/helphub
  • Contributing to Helphub: https://make.wordpress.org/docs/handbook/helphub/getting-started-with-helphub/
  • Staging Site: https://wp-helphub.com/

Docs Sprint – November 1st

The Seattle WP Meetup’s next monthly WordPress Docs Sprint is coming up on Saturday, November 1st.

We need all experience levels – this isn’t just for coders. We need writers, screenshot-takers, editors, readers, and of course, developers.  If you show up, we’ll find a way you can help.

Questions

What if you’re not in the Seattle/Tacoma area?

We’ll use Slack for team communication while we’re at the meetup, so if you’re joining from another state, country, or planet, you can participate as long as you’ve got a good internet connection.

If you don’t already have a Slack account, go to https://make.wordpress.org/chat/ and signup for an account. Once you log in, join us in the #docs channel.

How long are the Contributor Meetups?

From 10am – 2pm (18:00 – 22:00 UTC).

How do I join you?

  1. Show up in person or on Slack in #docs
  2. You can join the Seattle WordPress Meetup on Meetup.com (optional)
  3. RSVP for meetups that interest you and ask any questions you have
  4. We’ll help you get started contributing to Docs.

#sprint

Handbook Tasks – WordCamp Sofia Contributor Day 2013

Howdy WordCamp Sofia Contributors!

Thanks a bunch for helping with WordPress documentation – we all really appreciate your help!

We’ve been focusing a lot on the Theme Developer Handbook and Plugin Developer Handbook, which both need a good deal of work.

For most people, the toughest roadblock to contributing is just getting started, so hopefully this will help.

Where to Go

The jumping off point for all docs-related efforts is: make.wordpress.org/docs/ – In the sidebar, you’ll see links to the Handbooks along with the Spreadsheets we use to track their progress.

  1. The Theme Developer Handbook is at: http://bit.ly/WPThemeHB
    • . . . and the spreadsheet that we use to track Theme Developer Handbook progress is at: http://bit.ly/WPThemeHB_Content
  2. The Plugin Developer Handbook is at: http://bit.ly/WPPluginHB
    • . . . and the spreadsheet that we use to track Plugin Developer Handbook progress is at: http://bit.ly/WPPluginHB_Content
  3. The IRC channel we use is at #wordpress-sfd on Freenode.
    • This is a great place to ask questions, post links to docs for review, and cheer each-other on.

Getting Started

If you haven’t already, you’ll want to:

  1. Read the Handbook Style Guide
  2. Review the Handbook Tutorial Template
  3. Find a topic in the Theme or Plugin developer spreadsheet that interests you
  4. Check the Needs column of the spreadsheet to see if there are specific things that are needed in this document
  5. Add your name to the Responsible column in the spreadsheet
  6. Write or edit in HTML or Markdown and give it to Mario Peshev or email it over to me at eric [at] ivycat.com and we’ll post for you.

What if I’m not a Writer?

If you’re not comfortable writing or editing, you can also help by:

  • Creating code snippets for examples
  • Taking relevant screenshots
  • Reading existing documentation and making comments regarding improvements

If you’re completely overwhelmed and not sure where to start, you might start by reading through the Handbook and, when you’ve got questions, find missing content, or see improvements, please feel free to work on the document, or make comments in that document’s comment section.

I’m here to help in any way I can, so feel free to ping me (@sewmyheadon) or Mario (@no_fear_inc), or post to the #wordpress-sfd IRC channel if you have any questions.

Thanks again and have a great WordCamp!

#contributor-day, #docs, #wcsofia