[wp-meta] [Making WordPress.org] #5815: Initiative to create thorought developer documentation of all core javascript files

[Making WordPress.org]

#5815: Initiative to create thorought developer documentation of all core
javascript files
---------------------------+--------------------
 Reporter:  caseymilne     |      Owner:  (none)
     Type:  enhancement    |     Status:  new
 Priority:  normal         |  Milestone:
Component:  Developer Hub  |   Keywords:
---------------------------+--------------------
 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.

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/5815>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org