Designer & Developer Handbook

[chrisvanpatten]

This is a tracking ticket for the Designer & Developer Handbook. The goal is to use this ticket to get us to…

1. Consolidate discussion
2. Consolidate GitHub issues related to the dev documentation into this ticket
3. Map PRs to sections of the dev handbook outline

Outline

1. Building blocks and plugins
   1. Tutorials
      1. Build your first block (Documentation/Tutorial issues/enhancements #6185)
      2. Build your first plugin sidebar
      3. Extend a block
      4. Extend the editor
   2. Developer Reference
      1. Blocks API
         1. registerBlockType
         2. attributes
         3. edit and save (Documentation: More examples of save() callback of block #4070)
      2. Plugins API
      3. Components (Add visual indicator to Gutenberg core components? #7327)
      4. Registered scripts
      5. Block filters
      6. Editor filters & slotfills
      7. Parsing and rendering blocks with PHP functions (Wanted: docs on how to parse blocks on front-end #6358)
   3. Designer Reference
      1. Human Interface Guidelines
      2. Preparing block icons
2. Theming for the new editor
   1. Theme support list
   2. Block HTML & CSS reference (classes to target)
   3. Editor styles
   4. Block style variations
3. Backwards compatibility
   1. Meta boxes
      1. No server side validation or add_settings_error (Meta boxes: server side validation with add_settings_error isn't possible #3964)
   2. Important deprecations/changes from 4.x (Document known changes in editor behavior #4186)
4. Resources
   1. Articles
   2. Meetups
   3. Talks

[0aveRyan]

@chrisvanpatten for 1. i. a. (build first block), I think it'd be great to emphasize that Custom Block Styles are much easier to register than building a custom block.

Another general thought is it's going to be important to emphasize that core @WordPress libraries shouldn't be repackaged with vendor bundles and that something like webpack's externals should be used in conjunction with defining the needed libraries as dependency strings during wp_register_* so that multiple copies of the same script aren't loaded.

[0aveRyan]

@chrisvanpatten took a second pass on the outline

1. Technical Introduction
   1. How It Works
   2. Production Dependencies
   3. Build Process Dependencies
   4. Best Practices
2. Building Themes
   1. Theme Support
   2. Frontend CSS
   3. Admin Editor CSS
   4. Block Style Variations
   5. Preparing Dark Themes
   6. CSS Reference
3. Building Plugins
   1. Custom Block Styles
   2. Custom Blocks
   3. Extending Blocks
   4. Block Categories
   5. Editor Plugins
4. Developer Reference
   1. Blocks API
   2. Plugins API
   3. Template API
   4. Using Higher-Order Components
   5. Interacting with the Data Store
   6. Block Filters
   7. Editor Filters
   8. Parsing Blocks in PHP
5. Design Reference
   1. Human Interface Guidelines
   2. Preparing Block Icons
6. Backwards Compatibility
   1. Meta Boxes
   2. Deprecations
7. Resources
   1. Articles
   2. Meetups
   3. Talks
   4. Open-Source Examples

[chrisvanpatten]

@0aveRyan This is killer. Would you be open to updating #11817 to use this new structure? I can do it too, but if you have bandwidth this afternoon that'd be awesome.

[0aveRyan]

@chrisvanpatten in my last meeting of the day and then I'll dive in on that

[chrisvanpatten]

@0aveRyan awesome thanks! don't worry about updating the manifests; I'm working on a script to do that automatically.

[skorasaurus]

Although there was a merge at #11817; this outline isn't visible at https://wordpress.org/gutenberg/handbook/designers-developers/
Is it intended to be ?

[oandregal]

Is this still relevant now that the handbook has been reorganized and migrated to https://developer.wordpress.org/block-editor/ ?

[chrisvanpatten]

Let’s close it; I think we’ve accomplished the changes we set out to make. Thanks everyone for your amazing help!

🚀