WordPress.org

Making WordPress.org

Opened 3 months ago

Last modified 4 weeks ago

#4376 accepted enhancement

Centralized API handbook

Reported by: casiepa Owned by: coffee2code
Milestone: Priority: normal
Component: Developer Hub Keywords:
Cc:

Description

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 (16)

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


3 months ago

#2 @Kenshino
3 months 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.


3 months ago

#4 @casiepa
3 months 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 months ago

#6 @coffee2code
3 months 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 months 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
  • HTTP API
  • Filesystem
  • Metadata
  • Options
  • Plugins
  • Quicktags
  • REST API
  • Rewrite
  • Settings
  • Shortcode
  • Theme Modification
  • Transients
  • XML-RPC
  • 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 months ago

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


2 months ago

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


7 weeks ago

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


5 weeks ago

This ticket was mentioned in Slack in #meta-devhub by kenshino. View the logs.


4 weeks ago

#13 @coffee2code
4 weeks ago

In 8961:

Developer: Create Common APIs handbook.

Handbook is currently only accessible to logged-in users.

See #4376.

#14 @coffee2code
4 weeks ago

In 8962:

Developer: Customize section title for Common APIs handbook.

See #4376.

#15 @coffee2code
4 weeks ago

  • Keywords 2nd-opinion removed
  • Owner set to coffee2code
  • Status changed from new to accepted

The Common APIs handbook has been created and accessible (only to logged-in users) via https://developer.wordpress.org/apis/.

I've held off on adding a DevHub front page block for it until later. Relatedly, the details for the block could stand to be agreed upon. Currently I have:

This ticket can be closed out once the handbook has been added to the DevHub front page and made publicly accessible.

@casiepa: You're already a handbook editor, but be sure to coordinate with the rest of the Docs team to confirm the structure and style of the handbook before getting too far with things.

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


4 weeks ago

Note: See TracTickets for help on using tickets.