How to update the docs


  • Follow the Blocks Writing Guidelines
  • 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.




  • 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.
Last Updated: November 2019