47 |
48 | Interestingly enough, the distribution was consistent across all age and gender demographics. No matter how young or old the customer was, they typically preferred a casual tone and style in writing.
49 |
50 | ### **Context matters**
51 |
52 | Although customers generally prefer a more human, friendly tone, each support interaction is different. A service staff must be able to assess the situation and any emotion at play, think about the right style of approach, and react appropriately.
53 |
54 | For example, according to Jay Ivey, customers are likely to interpret a casual attitude in a delicate situation as being insensitive, condescending, or otherwise inappropriate. It just may not create the most productive mood.
55 |
56 | 
57 |
58 | An overwhelming majority of customers—78%—would be dissatisfied if their request was denied using a casual tone. In contrast, if a request was granted in a formal tone, only 35% said it affected their satisfaction.
59 |
60 | ### **Pro tip:**
61 |
62 | A support staff must be careful when dealing with those who are angry or upset. No need to learn the hard way here about the power of emotion: Those customers are, understandably, much more likely to be sensitive to the tone in the contents of the exchange. The best course of action is to keep the tone neutral and rely on [other techniques](https://blog.zopim.com/2013/12/03/deal-unhappy-customers/) to help defuse the situation and create a more productive mood. It's OK if your support interaction winds up on Twitter — as long as the story being told is a happy one.
63 |
64 | ### **Colloquialisms are sometimes inappropriate**
65 |
66 | Casual banter can sometimes go too far. Yes, it's a popular default style, and it can make everyone feel at ease, especially if the speaker or writer representing your company is naturally funny.
67 |
68 | In the last decade emoticons \[ ;P ], emoji, and colloquialisms \[“lol”] have become commonplace in the contents of digital communication. They add some extra character to a sentence or a story, sure, sure, but is it something that every reader can appreciate?
69 |
70 | 
71 |
72 | Although 49% of customers didn’t consider any of the listed options as too casual, 35% felt that emoticons were too informal for support services. Similarly, 26% said the same about colloquial words.
73 |
74 | Jay Ivey does offer a caveat here. Unlike support emails, live chat is inherently more casual. The back-and-forth style of chat makes it easier to remember there’s a real human being with some personality on the other end. Sometimes, liberally using emoticons or colloquialisms in the contents of the chat might actually be appropriate, just so long as agents are conscientious of the reader's needs on the other side.
75 |
76 | ### **Pro tip:**
77 |
78 | Read the situation. If the customer is using emoticons or colloquial language, feel free to respond in kind. Just don't go overboard and treat it like a bad Twitter post.
79 |
80 | You are all characters in a story here: Staying alert to how the customer is feeling can help an agent with the right expression or word choice. A thoughtful approach to the content fueling these interactions can help ensure the message an agent communicates is well received.
81 |
82 | ### Use first names.
83 |
84 | * Don't use titles, like `Mr.`, `Mrs.`, `Miss`, or `Ma'am`
85 | * If you're not sure what their name is, address them by saying `Hey there` or `Hi again` (if they write back)
86 |
87 | ### Always use a salutation.
88 |
89 | * Opening: `Hey` or `Hi`
90 | * Closing: `Cheers,` or `Thanks!`
91 |
92 | ### Thank them when appropriate, especially in the first response.
93 |
94 | * Providing feedback:`Thank you for reaching out to us.`
95 | * Don't use this for every one of their responses; otherwise it will seem too scripted.
96 |
97 | ### Say "We're sorry" when needed.
98 |
99 | If you're late to respond to a friend or if they're experiencing an issue, you would say you're sorry.
100 |
101 | * Bugs/issues: `We're so sorry you're experiencing this issue.`
102 |
103 | ### No grammar, spelling, or syntax issues.
104 |
105 | * Have [**Grammarly**](https://chrome.google.com/webstore/detail/grammarly-for-chrome/kbfnbcaeplbcioakkpcpgfkobkghlhen?hl=en) turned on in Chrome when you're working to prevent errors.
106 | * The [**Grammarly blog**](https://www.grammarly.com/blog/) is a good resource.
107 |
108 | ### Be positive.
109 |
110 | * That's a great question!
111 | * Start with the good, not the bad.
112 |
113 | (e.g. `Try this` instead of `We can't help`)
114 |
115 | ### Use "we", not "I".
116 |
117 | * You're speaking on behalf of the company in every email you send.
118 |
--------------------------------------------------------------------------------
/engineering/best-practices/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | description: >-
3 | Here are some of the recommendations to achieve optimal code quality and to
4 | follow best practices.
5 | ---
6 |
7 | # 🎯 Best practices
8 |
9 | * [Data Fetching](data-fetching.md)
10 | * [Prefer inferred types over explicit ones](prefer-inferred-types-over-explicit-ones.md)
11 | * [Prefer early returns](prefer-early-returns.md)
12 | * [Avoid comparing multiple values with `includes`](avoid-comparing-multiple-values-with-includes.md)
13 | * [Validate using zod instead of type casting](validate-using-zod-instead-of-type-casting.md)
14 | * Don't hesitate extracting nested code into new React Components
15 | * Code organization tips
16 | * Consider state machines over simple boolean states
17 | * Don't extract function props outside render just because
18 | * Make proper user of React Children
19 | * Authed CRUDs should be user centric
20 | * Prefer adding tRPC queries over `/api/..` endpoints on `web`
21 | * [Prefer `defaultHandler` for simple API handlers](prefer-defaulthandler-for-simple-api-handlers.md)
22 | * [Prefer Composition over Prop Drilling](prefer-composition-over-prop-drilling.md)
23 | * [Avoid Prop Drilling](avoid-prop-drilling.md)
24 | * [prefer-ternaries-over-short-circuiting-and-and-for-react-components.md](prefer-ternaries-over-short-circuiting-and-and-for-react-components.md "mention")
25 |
26 | {% hint style="info" %}
27 | TODO: Expand each of these bullet points
28 | {% endhint %}
29 |
30 | ### Additional resources
31 |
32 | * [https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/basic\_type\_example/](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/basic\_type\_example/)
33 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/engineering/best-practices/avoid-comparing-multiple-values-with-includes.md:
--------------------------------------------------------------------------------
1 | # Avoid comparing multiple values with \`includes\`
2 |
3 | Instead of doing:
4 |
5 | ```typescript
6 | if (req.method === "POST" || req.method === "PUT" || req.method === "DELETE") {
7 | console.log("Method allowed");
8 | }
9 | ```
10 |
11 | Do:
12 |
13 | ```typescript
14 | if (["POST", "PUT", "DELETE"].includes(req.method)) {
15 | console.log("Method allowed");
16 | }
17 | ```
18 |
19 | This will very situational, but when comparing multiple values you can use include to improve legibility. Also make sure that an [early return isn't more appropriate first](avoid-comparing-multiple-values-with-includes.md#prefer-early-returns).
20 |
--------------------------------------------------------------------------------
/engineering/best-practices/avoid-prop-drilling.md:
--------------------------------------------------------------------------------
1 | # Avoid Prop Drilling
2 |
3 | {% embed url="https://twitter.com/asidorenko_/status/1623751929863016450?s=61&t=yL8-sVU9YPvKV53r6jcV1A" %}
4 | TLDR
5 | {% endembed %}
6 |
--------------------------------------------------------------------------------
/engineering/best-practices/data-fetching.md:
--------------------------------------------------------------------------------
1 | # Data fetching
2 |
3 | When fetching for data in your Next.js pages you can follow the recommended approach for handling prefetching and loading states:
4 |
5 | .png>)
6 |
7 | This will allow to have this data already ready in the initial load, reducing the number of loading states and null/undefined checks.
8 |
--------------------------------------------------------------------------------
/engineering/best-practices/disallowing-the-use-of-unrestricted-metadata-fields.md:
--------------------------------------------------------------------------------
1 | # Disallowing the use of unrestricted Metadata fields
2 |
3 | #### WHY?
4 |
5 | PostgreSQL has long been esteemed for its robustness and its ability to handle a wide variety of data types, including JSON. JSON support in PostgreSQL allows for a non-relational representation of data structures, providing flexibility in how data is stored and retrieved. However, while there are scenarios where JSON is beneficial, certain limitations exist that can make its use in PostgreSQL disadvantageous.
6 |
7 | Opting to use JSON because it's "easy" is akin to just spinning up a MongoDB cluster to store data we are not caring about enough to restrict with a specific schema.
8 |
9 | #### PERFORMANCE DRAWBACKS
10 |
11 | JSON data is not stored in a pre-defined manner, which can lead to significant performance overhead. The database engine must parse JSON data for each query, which can be computationally expensive, leading to slower query performance compared to traditional relational data storage. This is particularly noticeable in large-scale databases or when executing complex queries that require the database to sift through sizable JSON documents.
12 |
13 | #### INDEXING DIFFICULTIES
14 |
15 | While PostgreSQL does allow for indexing JSON data, these indexes are typically not as efficient as those on traditional column data. Indexing a JSON field requires the creation of a functional index on the specific key within the JSON blob, which can lead to a proliferation of indexes and increased maintenance overhead. Furthermore, these indexes can be less performant, especially if the queries are not well-aligned with the index structure.
16 |
17 | #### DATA MODIFICATION
18 |
19 | Modifying data within a JSON field can be cumbersome. Unlike standard fields that can be updated directly using SQL 'UPDATE' statements, changing a single value within a JSON document often requires rewriting the entire document. This can lead to inefficient data manipulation operations, particularly for larger JSON documents.
20 |
21 | {% hint style="info" %}
22 | #### HOW TO SOLVE THIS?
23 |
24 | In most cases, we're using metadata to store responses from third party APIs, e.g. Google Calendar, Stripe, etc. For most of these we're already defining a zod schema to parse said responses, thus, why not create columns or tables directly for those responses? We're getting type safety by the generated Prisma types, and we can index those fields (eg stripeCustomerId, which is currently living under the `metadata` within a User's object)
25 | {% endhint %}
26 |
27 | ####
28 |
--------------------------------------------------------------------------------
/engineering/best-practices/dont-modularize-prematurely.md:
--------------------------------------------------------------------------------
1 | # Don't modularize prematurely
2 |
3 | The reason why you should not split files if they're not being used in more than one place is because it can lead to unnecessary complexity and maintenance overhead. If a file is only being used in one place, there is no need to split it into multiple files. This can make it harder to navigate and understand the codebase.
4 |
5 | On the other hand, splitting functions and components as much as possible can be beneficial. It can help with code organization, reuse, and testability. By breaking down large components into smaller ones, you can create a more modular and flexible codebase. This can make it easier to maintain and evolve the code over time.
6 |
7 | Collocating related code in the same file can also improve code organization and readability. If you have related code scattered across multiple files, it can be harder to understand how everything fits together.
8 |
9 | In summary, the decision to split files or not should be based on whether it improves code organization, readability, and maintainability. It's okay to split functions and components as much as possible, but don't split files unnecessarily. Collocating related code in the same file can also be helpful.
10 |
--------------------------------------------------------------------------------
/engineering/best-practices/e2e-tests-best-practices.md:
--------------------------------------------------------------------------------
1 | ---
2 | description: >-
3 | These are some basic principles that should be respected when working with E2E
4 | tests. Failure to follow these practices can be a motive for PR rejection.
5 | ---
6 |
7 | # E2E Tests Best Practices
8 |
9 | * A test should avoid using Text Locators: `page.locator('text=`
10 | * Add a proper to data-testid to the HTML element and retrieve it by using page.getByTestId
11 | * From [Playwright docs](https://playwright.dev/docs/locators#locate-by-test-id):
12 | * > Testing by test ids is the most resilient way of testing as even if your text or role of the attribute changes the test will still pass. QA's and developers should define explicit test ids and query them with page.getByTestId(). However testing by test ids is not user facing. If the role or text value is important to you then consider using user facing locators such as role and text locators.
13 | * A test should be able to run locally as well as on CI
14 | * A test should be able to be run multiple times and expect a consistent result
15 | * A test should not introduce side-effects that may affect other tests running in parallel
16 | * A test should use expect(page).toHaveURL() so we can fail fast if a new unexpected redirection is introduced
17 | * A test should avoid using fixed seeded records for testing.
18 | * This conflicts with parallelization and consistency
19 | * A test should reset the DB state to be the same after running tests than it was before running them.
20 | * This means all created records should be properly cleaned up after tests are run
21 | * If seeded records were used, return them to their original state afterwards.
22 |
23 | ### TODO
24 |
25 | * Guide for debugging E2E failures
26 | * What to do when checks fail?
27 | * How can I know where to look?
28 | * Recommended Tools and extensions
29 | * Workflow recommendations for working with E2E tests
30 |
--------------------------------------------------------------------------------
/engineering/best-practices/only-select-data-you-need.md:
--------------------------------------------------------------------------------
1 | # Only select data you need
2 |
3 | 1\) Increased performance overhead: When you select all columns from a table, Prisma retrieves all the data associated with each row, which can result in a significant performance impact. This includes reading unnecessary columns and transferring a large volume of data between your application and the database.
4 |
5 | 2\) Unnecessary data exposure: Selecting all columns exposes sensitive data that might not be required by your application. This can pose security risks, especially if the table contains sensitive user information or proprietary data. (In our case app credentials and booking information)
6 |
7 | .png>)
8 |
9 | TLDR: Never use Includes - use select
10 |
11 | * Select selects only the fields you specify explicitly
12 | * Include selects the relationship AND all the fields of the table the relationship belongs to
13 |
14 | {% embed url="https://www.prisma.io/docs/concepts/components/prisma-client/select-fields" %}
15 |
--------------------------------------------------------------------------------
/engineering/best-practices/prefer-composition-over-prop-drilling.md:
--------------------------------------------------------------------------------
1 | # Prefer Composition over Prop Drilling
2 |
3 | Instead of relying on prop drilling, let's try to take advantage of react children feature. Having this as an example:
4 |
5 | {% code overflow="wrap" lineNumbers="true" %}
6 | ```typescript
7 | import React from "react";
8 | import { Profile } from "./profile";
9 |
10 | function Header({ loggedIn, handleSetLoggedIn }) {
11 | return (
12 | <>
13 | 
 (1).png)
15 | 2. Create a new release in GitHub:\
16 | [https://github.com/calcom/cal.com/releases/new](https://github.com/calcom/cal.com/releases/new)
17 | 3. Type the new version and hit "Create new tag: vX.Y.Z on publish"\
18 | .png>)
19 | 4. Use the "Create auto generated release text" button\
20 |  (1).png>)
21 | 5. Publish release\
22 |  (1).png>)
23 | 6. Profit!
24 |
25 | ### Check for migrations
26 |
27 | This is important. When doing a release make sure you run proper migrations first.
28 |
29 | Also, important sidenote, if a migration is adding a new table. We need to re-grant proper permissions to each created username that are currently being used. Run these commands for each username (Replcing \
https://cal.localhost {
77 | reverse_proxy localhost:3001
78 | }
79 |
80 | https://app.cal.localhost {
81 | reverse_proxy localhost:3000
82 | }
83 | .png)
Documentation update tag
| LFE | looking for engineer |
| LFD | looking for designer |
| LFR | looking for review |
| SIU | Super Important and Urgent. Use very carefully. (When typing you need to shout a SIUUUU) |
| Destination calendar | The calendar that events are created on |
| Monorepo | Multiple projects (e.g. app, docs and API) all in one GitHub repository |
| Commit | Addition to the code |
| Pull request (PR) | The way in which code is reviewed and then added to the codebase. A PR is made of commits |
| Merge | If a PR is good, it is merged, which accepts the changes and ‘merges’ them into the codebase |
| i18n | Internationalization (translating text) |
| a11y | Accessibility |
| CTR | Click-Through Rate |
| UI | User Interface |
| UX | User Experience |
| Event types | Different events that you offer on your booking link. For instance, hiring (30 mins) and performance review (60 mins) are both examples of event types. |
| Opt-in booking | An event type where you must accept/deny the booking before it’s created |
| Slots | Time slots that are offered on your booking page that are determined to be free |
| RFC | Request for comments. Essentially a proposal, where we’re looping in the team to get their thoughts |
| Round robin | Schedules each person in the team. If a team is made up of persons A, B and C, the first booking goes to person A, second goes to B, third to C etc. |
| CalDAV | An open standard for calendars. Essentially a ton of different calendar providers (e.g. Yandex, NextCloud) all support CalDAV, which allows you to connect those providers to Cal.com |
| Kangaroo | A tall animal that hops around |
| Webhooks | A way for Cal.com to send data to an external server when something happens (e.g. booking created) |
| SAML SSO | A way for enterprises to let everyone in their company log in to any application, including Cal.com |
| Vercel | The platform that builds our code and publishes it to the live site |
| e2e | End to end testing. Essentially a robot that checks if our application is working each time we push code |
| Linting | A way to make code look nice and neat |
| .env | A file where you configure settings for Cal.com, like your database and email servers |
| WEBAPP_URL | The setting that tells Cal.com which URL it’s hosted on |
| TypeScript | An extension of the language JavaScript, which can do things like check if values are the correct type |
| API | A way to get data and perform actions on the Cal.com service using code |
| NPM package | Dependencies (things your app uses) can be packaged into NPM packages, which are bundles of code that you can use in other applications |
| Metadata | Data that is in a computer readable format, like JSON, which looks like {”make”: “Volvo”, “model”: “V40”} |