JavaScript Chat Summary for June 6th

Below is a summary of the discussion from today’s JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. chat (agenda, Slack transcript):

Pre-Discussion

• Conversation following last week’s meeting has been lively
• @adamsilverstein has created a ticketticket Created for both bug reports and feature development on the bug tracker. to discuss migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. to Webpack (#40894)
• There will not be a JavaScript Chat next week (June 13th)

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 APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. 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 CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 UIUI User interface 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 PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 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 (GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/) blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.” 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.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/)
    • UI Components – Search and view components with some customization interactivity
    • State selectors reference – Automated function documentation, extracted from JSDoc comments
• 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 ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. 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