diff --git a/plan/outline.md b/plan/outline.md index a5cc0d7..afae0d4 100644 --- a/plan/outline.md +++ b/plan/outline.md @@ -1,80 +1,300 @@ # Docs Outline -* What are web components - P0 (single page including sub headings) - * Custom Elements - * Shadow DOM - * Standard JS Modules -* Why web components - P0 (single page including sub headings) - * What do we mean by interop? - * Interop with HTML, frameworks, the browser - * Interop with file formats: Markdown vs MDX, etc. - * Interoperable composition with slots - * Interop with the future - * Use cases - * Standalone components - * Component sets and design systems - * Applications -* Related specs - P0 (single page including sub headings) - * MDN links - * GitHub repos with proposals - * What's left, ie. WCCG reports +## Overview + +This is an outline for the Docs section of the site, likely to be contained under the `/docs/` URL space. + +### Goals + +The goals and contents of this section were discussed at the [Nov 17th WCCG meeting](https://docs.google.com/document/d/1uCQmHT_UTHtrf1xSfbQD5Ko23CpJrEY53wPIg3QHA5k/edit). + +The "docs" category of content is intended to be evrgreen conceptual and reference information that fits into a single hierarchical content outline. Docs should be mostly factual and objective, outside of the shared opinions of the community group on the benefits of web components in general. + +As a category, docs are distinct from articles and blog posts, which may be relevant for a point-in-time, have more opinions shared by only a subset of the WCCG, and/or be how-to's, tutorials and news. + +### Docs MVP + +A [docs MVP](https://github.com/webcomponents-cg/docs-and-guides/issues/33) which could replace the current webcomponents.org includes: + +- [What are web components?](https://github.com/webcomponents-cg/docs-and-guides/issues/29) +- [Why web components?](https://github.com/webcomponents-cg/docs-and-guides/issues/30) +- [Related specifications](https://github.com/webcomponents-cg/docs-and-guides/issues/31) +- [Web Component Libraries](https://github.com/webcomponents-cg/docs-and-guides/issues/32) + +## Outline +*
What are web components? + + * URL: `/docs/what-are-web-components` + * Priority: P0 + * Issue: https://github.com/webcomponents-cg/docs-and-guides/issues/29 + * Page content: + * Custom Elements + * Shadow DOM + * Standard JS Modules + +
+ +*
Why web components? + + * URL: `/docs/why-web-components` + * Priority: P0 + * Issue: https://github.com/webcomponents-cg/docs-and-guides/issues/30 + * Page content: + * What do we mean by interop? + * Interop with HTML, frameworks, the browser + * Interop with file formats: Markdown vs MDX, etc. + * Interoperable composition with slots + * Interop with the future + * Use cases + * Standalone components + * Component sets and design systems + * Applications + * Who's using web components (Possibly separate page) + +
+ +*
Related specifications + + * URL: `/docs/specifications` or `/docs/standards` + * Priority: P0 + * Issue: https://github.com/webcomponents-cg/docs-and-guides/issues/31 + * Page content: + * MDN links + * GitHub repos with proposals + * What's left, ie. WCCG reports + * Cross-link to site's Community Protocols page + +
+ * Using web components - * Basics - * Definining, the custom element registry, and the single tag name scope - * Upgrading, and `:defined` - * Children and slots - * Events - * Using web components in HTML and vanilla JS - * Styling - * CSS Custom Properties - * ::part()s - * Using web components with frameworks - * Using web components in... - * Markdown (how to import in various systems) - * WordPress -* Writing web components - * Defining - * Custom element registries - * Self-registering vs not - * Defensive registration for special cases (CDN distribution) - * Lifecycle - * Basics: `observedAttributes`, `constructor`, `attributeChangedCallback`... - * Cleaning up resources in `disconnectedCallback` - * Shadow DOM - * attachShadow() - * open vs closed - * Encapsulation: DOM, events, CSS - * Just overview: more detail in Styling and Composition sections - * Slots - * Styling - * Encapsulation (more detail than) - * Shadow selectors: `:host`, `:host()`, and `::slotted()` - * CSS Custom Properties - * CSS Shadow Parts: `part` and `::part()` - * Constructible style sheets - * Theming - * Strategies for deep styling - * Dealing with data - * Designing both a property & attribute API - * Responding to attribute changes (`attributeChangedCallback`) - * Responding to property changes (accessors) - * Considerations about when to use methods - * Reflecting between properties and attributes - * Using events for data - * Publishing to npm - * Composition - * Slots - * Communicating with events - * Using children - * Accessibility - * Forms - * Web component libraries -* Community Protocols -* Community and Resources -* FAQ - * Myth-busting answers can go here - * Can custom elements really only take strings? - * Is it impossible to SSR web components? - * Why don't web components solve ___ that other frameworks do? - * ... -* Demos and Playgrounds (standalone or to accompany each piece of content?) + *
Basics + + * URL: `/docs/using-web-components` or `/docs/using-web-components/basics` + * Priority: P1 + * Issue: + * Page content: + * Importing definitions + * Using web components in HTML and vanilla JS + * Definining, the custom element registry, and the single tag name scope + * Upgrading and `:defined` + * Children and slots + * Events + +
+ + *
Styling + + * URL: `/docs/using-web-components/styling` + * Priority: P1 + * Issue: + * Page content: + * Shadow DOM encapsulation + * CSS Custom Variables + * ::part() + * Attributes (for elements that use attributes for styling) + +
+ + *
Using web components with frameworks + + * URL: `/docs/using-web-components/frameworks` + * Priority: P1 + * Issue: + * Page content: + * General considerations + * Setting attributes and properties + * Listening for events + * Slots + * Methods (and refs) + * Template type-checking and linting + * SSR + * Examples in React, Angular, Vue + +
+ + *
Using web components with other tools + + * URL: `/docs/using-web-components/tools` + * Priority: P1 + * Issue: + * Page content: + * Markdown (how to import in various systems) + * Eleventy + * Astro + * Jekyl, Hugo... + * CMSes: WordPress, Umbraco, Drupal, Laravel? + +
+ +*
Writing web components + + This section is about the concepts and APIs relevant to writing web components, which should apply to "vanilla" web components as well as most web component libraries. It is not a tutorial on writing vanilla web components. + +
+ + *
Defining custom elements + + * URL: `/docs/writing-web-components/defining` + * Priority: P1 + * Issue: + * Page content: + * Custom element registries + * Synchronous upgrade, and upgrade() + * Self-registering vs not + * Defensive registration for special cases (CDN distribution) + +
+ + *
Lifecycle + + * URL: `/docs/writing-web-components/lifecycle` + * Priority: P1 + * Issue: + * Page content: + * Basics: `observedAttributes`, `constructor`, `attributeChangedCallback`... + * Cleaning up resources in `disconnectedCallback` + +
+ + *
Shadow DOM + + * URL: `/docs/writing-web-components/shadow-dom` + * Priority: P1 + * Issue: + * Page content: + * attachShadow() + * open vs closed + * Encapsulation: DOM, events, CSS + * Just overview: more detail in Styling and Composition sections + * Slots + +
+ + *
Styling + + * URL: `/docs/writing-web-components/styling` + * Priority: P1 + * Issue: + * Page content: + * Encapsulation (more detail than) + * Shadow selectors: `:host`, `:host()`, and `::slotted()` + * CSS Custom Properties + * CSS Shadow Parts: `part` and `::part()` + * Constructible style sheets + * Theming + * Strategies for deep styling + +
+ + *
Dealing with data + + * URL: `/docs/writing-web-components/data` + * Priority: P1 + * Issue: + * Page content: + * Designing both a property & attribute API + * Responding to attribute changes (`attributeChangedCallback`) + * Responding to property changes (accessors) + * Considerations about when to use methods + * Reflecting between properties and attributes + * Using events for data + +
+ + *
Publishing to npm + + * URL: `/docs/writing-web-components/publishing` + * Priority: P2 + * Issue: + * Page content: + +
+ + *
Composition + + * URL: `/docs/writing-web-components/composition` + * Priority: P2 + * Issue: + * Page content: + * Slots + * Communicating with events + * Using children + +
+ + *
Accessibility + + * URL: `/docs/writing-web-components/accessibility` + * Priority: P1 + * Issue: + * Page content: + * Slots + * Communicating with events + * Using children + +
+ + + *
Forms + + * URL: `/docs/writing-web-components/forms` + * Priority: P2 + * Issue: + * Page content: + * Shadow DOM scoping and forms + * Form-associated-custom-elements + * formdata event + +
+ + *
Web component libraries + + * URL: `/docs/writing-web-components/libraries` + * Priority: P0 + * Issue: https://github.com/webcomponents-cg/docs-and-guides/issues/32 + * Page content: + * Links to client-side libraries + +
+ + *
Tools + + * URL: `/docs/writing-web-components/tools` + * Priority: P2 + * Issue: + * Page content: + * Links to IDE extensions, linters, etc + +
+ +*
Community Protocols + + * URL: `/docs/community-protocols` + * Priority: P2 + * Issue: + * Page content: + +
+ +*
Community and Resources + + * URL: `/docs/resources` + * Priority: P2 + * Issue: + * Page content: + * Links to chats, meetups, Twitter communities, etc. + +
+ +*
FAQ + * URL: `/docs/faq` + * Priority: P2 + * Issue: + * Page content: + * Myth-busting answers can go here + * Can custom elements really only take strings? + * Is it impossible to SSR web components? + * Why don't web components solve ___ that other frameworks do? + * ... + +