Documentation updates are managed through Clubhouse and prioritized by PMs just like other work.
The guiding principle is "ease of contribution". For now, it’s ok to have blank sections to be filled in later.
Design
Designers can update the content of design sections of docs without eng input. Updates to engineer sections of docs need to get engineer feedback.
Updates to the docs are made by pull request. Designers can update the relevant markdown files directly once this process is straightened out.
For changes to components and interactions, designers should create eng tickets and pair with an engineer.
Engineering
Engineers have authority to update eng-related sections of the docs without design input. Updates to design sections of docs need to get design feedback.
Updates to the docs are made by pull request. Getting a single review and approval is enough, Blocks team members are allowed to make documentation changes without review.
Every change made to components needs to be reflected in the eng section of the docs before the change is merged. This ensures components are tested and documentation and implementation are in sync.
“Every” significant variant of a component should have its own interactive example. (Use your judgement.)
This ensures complete documentation and easier testing.
If this becomes overwhelming, we’ll reevaluate.
Components that are “in progress” can live in a “Experimental” section. Here, incomplete work is especially ok.