JavaScript Chat Summary for June 6th

Below is a summary of the discussion from today’s JavaScript chat (agenda, Slack transcript):

Pre-Discussion

Topic: Managing Complexity

  • WordPress is first development experience for many, and we should ensure JavaScript onboarding is similarly positive
  • Documentation as lacking
    • Current state of the wp global documentation
    • Documentation is always an after-thought
    • We can try automated documentation, but it’s not human-oriented and helps only if you know already what you’re looking for
    • We’ll need a combination of both automated and hand-written documentation
    • Need higher-level documentation to answer the questions of “How do I do X?”
    • User-submitted code examples like those on developer.wordpress.org are effective beyond just what the API is, but also how it’s to be used
    • To start, we need a 10,000 foot view explaining surface area of JavaScript in WordPress (expanding Core Handbook)
    • Who is the target audience of documentation: those looking to integrate, or contribute directly to the core codebase? Each requires different writing approaches.
  • Identifying challenges
    • Preparing a development environment and knowing where to find source files, especially in light of desire to more heavily adopt Webpack into workflow
    • Understanding decisions made: Why a framework, how do we approach data, how data is stored
    • Ideal workflow to npm start and be set to develop
    • Testing, build tools, module patterns
  • What to document?
    • Documenting UI components is new consideration. React Storybook was raised an example for demonstrating shared UI library (proposed in Gutenberg)
    • Bridging the divide between Backbone + Non-Backbone (“new”) system
  • Where to draw the line between complexity and unfamiliarity?
    • No amount of documentation can make up for a confusingly complex design
    • Some level of unfamiliarity is expected because it’s a different language with different paradigms than what a PHP developer might be most familiar with (example: declarative, reactive components)
    • We sell ourselves short if we limit only to what people already know
  • Incrementally introducing more complex functionality
    • What are the small tasks that developers will start with in getting used to working with WordPress JavaScript? “Writing an editor (Gutenberg) block” is a more advanced case, but highlights need for emphasis on the interfaces we expose, not just the documentation
  • Audience of documentation
    • People learn differently: Video works best for some, text for others
    • Might consider building personas to represent different users of documentation
  • Tools for documenting
    • We should standardize on JSDoc, but available tooling is somewhat lacking
  • Examples / success stories
    • Vue / React / Redux – Incremental introduction
    • documentation.js – Static analysis tool for creating documentation
    • React Storybook – Interactive UI component explorer
    • Calypso (Note: pages have layout issues if not logged in to WordPress.com)
  • Thoughts on scaffolding / code generation tools, like vue-cli, create-react-app, or more granular scaffolding like those found in Ruby on Rails or Laravel workflows (models, controllers, etc).
    • Not sure yet what sorts of things we’d care to generate
    • Could be valuable in “Age of Front-End Tooling Complexity”
    • Works for some people, not for others

Open Floor

  • From a comment on the agenda, @omarreiss shared a proof of concept for React extensibility, and was happy with control React gives toward goal of extensibility
    • Other approaches were shared: Nylas plugins, Gutenberg considerations (1, 2, 3)
    • “Extensibility” proposed as a future meeting topic
  • @rmccue shared his success with rendering PHP-only columns in the List Tables prototype toward a goal of backwards compatibility, and invites for consideration whether this is something we’d want for wider use or if others have encountered similar issues.

#javascript, #summary