Learn how to craft yummy cards that everyone will love
We put a lot of love in shaping perfect Notion cards, as we know that this is the way that fellow team members will be kept up to date about what we do - our cards make our work visible. In particular, we want to facilitate the job of our peers that will be conducting peer reviews by providing them with everything that's needed for this.
So here's a list of what a good Notion card should look like, including the essentials and additional data depending on its context. We strive to stick to these guidelines.
Link to GitHub Pull Request (except if the card is part of a broader family of cards, where 1 key card holds the link to the Pull Request). If several repos are impacted, provide 1 link per repo, with the title of the repo in markdown above.
Description of the context in the details
Link to the Google Slides with business specifications
Status updates in the comments for long-lasting cards
Link to associated documentation
Explanation of why tests have failed (in the case of usual suspects)
Pictures used as card cover
User details (name and other) explicitly stated - we use IDs and links instead
Documents stored in the card - we use links to the Drive instead
Front-end changes cards
Snapshot BEFORE the change
Snapshot AFTER the change
Link to relevant Sentry issue
Link to Slack message in IT helpdesk channel (if relevant)
Explicit description of the tasks that should be run at deployment time (e.g. cap production strike:my_script)
Explicit description of the dependencies of the scripts (e.g., first deploy A then B)
Follow-up card for cleaning of the scripts if they are one-off operations