Initiative to create thorought developer documentation of all core javascript files

[caseymilne]

As code reference is being moved from Codex to DevHub we want to ensure there is a place for Javascript-specific documentation. To clarify this documentation is defined as:

1. Specifically Javascript files, classes, functions.
2. Not suitable for a general guide or tutorial, handbook.
3. Is thorough "developer reference" documentation, meaning for instance that in a JS class all functions must be listed to be considered "complete".

As a specific example view wp.media page on Codex: ​https://codex.wordpress.org/Javascript_Reference/wp.media

This wp.media example shows us both what type of existing documentation we have to migrate into DevHub. It also shows us what we may wish to avoid in DevHub. WP Media class has many undocumented features, properties and options that are not contained in that Codex page. A brief search outside the WP #docs ecosystem will find dozens of tutorials illustrating usage of wp.media. However none of these serve as a consistent, thorough or official source of developer reference documentation.

Currently in DevHub there is a range of sections dedicated primarily to PHP documentation. This initiative is to help ensure there is balance between the quality and thoroughness of Javascript documentation with the existing PHP documentation.

Why does Javascript need to be carefully documented in a similar manner to PHP? For the same reason we document PHP. Because if we don't, the only way to really understand how to utilize something is to find the original source code and read it. This is inefficient, it leads to thousands of developers duplicating the same process of discovery of information, instead of rapidly digesting quality documentation. The gap in JS docs currently leads to a heavy reliance on 3rd party tutorials. It is much faster today for a developer to search for "how to use a WP script" such as wp.media, than it is to find and utilize any WP core docs. This won't change unless DevHub prioritizes javascript documentation in a manner than helps to create search indexing.

Here are some key goals for this initiative:

1) Documentation of JS is equally thorough to that of PHP currently and keeps pace with it permanently in the future.

2) Javascript documentation is handled in a "reference" format first, meaning thorough and structured documentation of each function/class. As useful as examples of guides are, these should be layered on top of quality "reference" docs.

3) Structure of the JS dev docs support supplementary documentation (handbooks, guides, tutorials) being able to link to these doc references in a similar way that we currently have with PHP.

Contributions Welcomed and Supported

All of the ideas shared above are open to discussion and improvement. Please share mention of any existing projects or plans that relate to JS documentation. This is also a good place to volunteer to join #docs and/or pledge to contribute JS-specific documentation.

[pbiron]

@herregroen started an effort to achieve this several years ago, I'm not sure where it ended up.