Perfect Notion cards

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.

Checklist

All cards

Essentials:

• Team member attributed

• Label(s) attributed

• Explicit title in English (see writing good titles)

• 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.

Nice-to-have:

• 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)

Avoid:

• 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

Bug cards

• Link to relevant Sentry issue

• Link to Slack message in IT helpdesk channel (if relevant)

Deployment cards

• 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

Writing good titles

Choosing relevant labels