rfc: vNext documentation

[EisenbergEffect]

💬 RFC

In preparation for vNext releases, we need to make many updates, additions, and improvements to our documentation. This RFC attempts to gather that plan into a single place. This RFC does not cover the site home page, which also needs updates. It only covers our documentation.

Organization

At present, our documentation is scattered across the repo, with each package having a sub docs folder. Initially, our reasons for doing this were:

• We had a legacy “root” docs folder, so we could not put our new docs at the root when we were first writing content.
• We thought it would be nice to have the individual docs for each library as part of the library package structure.

Some things have changed in the last few years though.

• We no longer have a legacy root docs folder.
• FAST has grown significantly and organizing many docs along package lines doesn’t always make sense, especially when those docs need to reasonably cross-reference one another.

Proposal

I’d like to move all the documentation to a root docs folder in the FAST monorepo. I believe this will make the documentation more discoverable and easier to map from the site to the repo. We should also be able to simplify our docs build process by centrally locating the content.

Content

The current docs need organizational and content improvement, especially considering the new approach vNext proposes for design systems and the breadth of new features and capabilities that are now available.

ToC Proposal

I’d like to propose the following Table of Content for our v2 documentation:

• Introduction
• Building Components
  • Same pages as before plus…
  • Advanced
    • Custom Security Policies
    • Custom Bindings
    • Custom CSS Directives
    • Custom HTML Directives
    • Dynamic Composition
    • Debugging FASTElement
    • Testing Components
    • Kernel Sharing
    • Performance Optimization
• Creating Design Systems
  • Getting Started
  • Design Tokens and Adaptive UI
  • Customizing Foundation Components
  • Component Guides
    • one page per component…
• Scaling Apps and Experiences
  • W3C Pending Task Protocol
  • W3C Context Protocol
  • Dependency Injection
  • State Management
  • Cross-component Communication
  • Code Organization and Conventions
  • Routing
    • May have a number of sub-pages
• Server-side Rendering
  • Getting Started
  • Creating Universal Components
  • Customizing your Server
  • Client Hydration Patterns
• Code Examples
  • Introduction
  • Page per example category…
• Integrations
  • Same pages as before…
• Tools
  • FAST CLI
  • Visual Studio Code
  • Hot Module Reload
• API Reference
  • Same pages as before…
• Community Contribution
  • Same pages as before plus…
  • Steering Committee
• Resources
  • Same pages as before plus…
  • Error Codes
  • Migration Guide
  • Working without Decorators

We need to keep most of the content we already have, but update it in various places. In addition to that, there’s a lot of new content we need to add. Below is an explanation of a few of the new areas.

Building Components (Advanced)

We need to document more of the customization points that are specific to FAST. However, we don’t want this intermingled with the basic fast-element content, as I think that would be off-putting to new community members and overwhelming. I’m proposing that we nest that in an “Advanced” section which we can point out in the “Next Steps” section of the existing documents. We need this content but don’t want folks to feel obligated to read it until they need to.

Creating Design Systems

With our new emphasis on the FAST CLI and the rapid creation of design systems, I think we need to re-write all the content in our design systems and components sections. We should approach this from the perspective of someone new to FAST who wants to rapidly stand up a design system and then customize it. Here’s a bit more detail on what I think the new pages should cover:

• Getting Started - This should introduce folks to the idea of a design system and to tokens. It should show how to use the CLI to setup a design system along with the most common customizations. We may even want to have a zip file or repo that people can download with the output of the default CLI settings so folks who don't want to use the tool can still get going easily.
• Design Tokens and Adaptive UI - This should go into detail on how to use tokens and adaptive UI. The advantages of the system should be clearly explained. The docs should also list and explain the purposes of the various tokens. It should teach how to customize values and recipes as well as how to use the tokens to do common tasks such as light/dark switching and density changes. We should explicitly cover how to add additional colors into a system, such as the common “secondary color”.
• Customizing Foundation Components - This page should give an overview of the approach for how to customize a foundation component. It should start with the most basic customizations and progress to the most advanced. It should introduce people to the component guide pages as resources when customizing a specific component.
• Component Guides - Here we should have a page for each foundation component that covers the API of that component, its default anatomy, recommendations for default styles (particularly functional styles), accessibility considerations, etc. It should have example uses of the component and also examples of the most common customizations that we are aware of (e.g. animating the selection of tabs).

Scaling Apps and Experiences

We have an equivalent section for this today but there’s very little content. We need to expand this section with additional content based on the common questions and scenarios that people have when they start building larger experiences with Web Components. This should also be a good place to educate folks on new W3C protocols, which are important for interop in larger systems.

Server-side Rendering

We should have a top-level section for SSR so that it’s clear that we support this capability. There is enough content to fill out several pages. Nick has written some of this content already. It probably just needs to be re-organized, extended, and moved here.

Code Examples

This is a completely new section which I would like to see focused on copy/paste code. No long narratives to read. Just example titles, with one or two sentences describing the scenario, then a block of code that can be copied and dropped directly into a project. We should organize this by groups of examples, such as: templating, design tokens, architecture, etc.

Interactivity

We should have more example code throughout and we should have examples running inline via some sort of sandbox experience. This is especially important for the foundation components and design tokens.

[EisenbergEffect]

I'd also like to add a "Tutorials" section. I think that probably has to come after we get the basic content in place though.

[KingOfTac]

I think the stackblitz templates I've been working on would fit somewhere in the Code Examples/Tutorials area. They may need their own home however since they are bigger than what you describe the code examples to be but not exactly a full blown tutorial either. They're more so meant for someone to quickly clone and have an environment already setup where they can play with a specific feature set of FAST and try things out.

[huynhicode]

Yay, I am excited for vNext documentation @EisenbergEffect . Looks great at first glance. I like the expansion of the "Creating Design Systems" section and the documentation being geared toward those new to FAST.

[LorenzKahl]

Looks great. I‘d love to see the addition of a DX section on „How to best setup VSCode for FAST Development“.

[LorenzKahl]

Answer to myself:
https://www.fast.design/docs/tools/vscode

Still, this doesn't give me "jump to definition" or Emmet-style expansion in CSS, but it's okay for starters ;-)

[usrrname]

I believe newcomers might benefit from clear distinction between the roles of fast-foundation vs fast-components and fast-element... getting a lot of "why does the doc say this but you tell me that" questions from people at work.

Update: nevermind, I see it is at https://www.fast.design/docs/introduction/ ...

[janechu]

We are taking this issue and subsequent feedback into consideration for the launch of v2 @microsoft/fast-element, closing this issue as it is now out of date with our current goals see #6955.