Making WordPress.org

Opened 6 weeks ago

Last modified 9 days ago

#4376 new enhancement

Centralized API handbook

Reported by: casiepa Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords: 2nd-opinion


I'm working a lot with APIs all over the WordPress world:

A centralized handbook with all API info, including parameters and extended with examples would a really a great tool for developers.

I can provide all info for the WordPress.tv one and can provide lots of examples for the other ones, so please let me know how we can work on this together.

Change History (9)

This ticket was mentioned in Slack in #docs by casiepa. View the logs.

6 weeks ago

#2 @Kenshino
6 weeks ago

  • Keywords 2nd-opinion added

Hey - I'm quite supportive of this.

This does change DevHub's role slightly - in the manner that it'd not just be the holding place for WordPress development code reference and handbooks. But it'd also hold the docs for developing against the WordPress.org infrastructure.

It still holds through for the persona mandate - as a developer, I should only need to go to DevHub to get all my information.

What do you think @coffee2code ?

This ticket was mentioned in Slack in #wptv by casiepa. View the logs.

6 weeks ago

#4 @casiepa
3 weeks ago

Waiting for a final place, I published some WordPress.tv API info on https://make.wordpress.org/tv/handbook/wordpress-tv-api/

This ticket was mentioned in Slack in #docs by kenshino. View the logs.

3 weeks ago

#6 @coffee2code
3 weeks ago

I'm on board with hosting API document in DevHub. APIs are generally a developer-related sort of thing and having them centrally located alongside other dev docs seems reasonable.

Looking at it from another angle, I'm not sure where else would be better for API docs to be hosted. The alternative for many, like the WP.tv API, would likely be in the handbook on their team's Make site, but those sites are intended for contributors. It muddies their purpose if developer-focused or user-focused documentation also exists there.

#7 @atachibana
3 weeks ago

I am 100% agree to "APIs Handbook" that will gather WordPress.org APIs and Core APIs listed in right side of https://developer.wordpress.org/reference/. Currently, Plugins Handbook covers some of them but many API entry pages remain in Codex. If we can provide them in DevHub, developer must feel convenient.

I have some proposal based on the last docs team meeting with @Kenshino and @milana_cap

Page Structure

Each API page (except REST API, which has independent handbook) should have Overview, Description, Usage examples and list of functions.

Table of Contents

  • Dashboard widgets
  • Database
  • Filesystem
  • Metadata
  • Options
  • Plugins
  • Quicktags
  • Rewrite
  • Settings
  • Shortcode
  • Theme Modification
  • Transients
  • WordPress.org
  • Central (for WordCamp)
  • WordPress.tv
  • Translation

Creation Workflow

  1. (meta) Create page structure under the https://developer.wordpress.org
  2. (docs) Migrate Codex Pages or Copy from Themes/Plugins Handbook to there
  3. (core) Review and Update by the Core reps. Some of contents might be out of date.
  4. (docs) Release

This ticket was mentioned in Slack in #docs by atachibana. View the logs.

3 weeks ago

This ticket was mentioned in Slack in #docs by kenshino. View the logs.

9 days ago

Note: See TracTickets for help on using tickets.