> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chartcastr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User notes

> Write free-text descriptions for your charts or source groups so the Chartcastr AI understands what the data represents and why it matters.

## Overview

User Notes let you provide context about a specific chart or a collection of charts directly in the product. This context is included in pulse summaries and helps the AI understand what your data represents.

<Note>
  User Notes are a quick way to add context, but for comprehensive business documentation, consider using External Context ([Google Sheets](/analysis/context/google-sheets), [Google Docs](/analysis/context/google-docs)) instead. Both can be mapped to [Single Sources](#assignment-options) or [Source Groups](/admin/sources/source-groups).
</Note>

## What are User Notes?

User Notes are a text field where you describe what a chart shows and why it matters. The AI includes this description when generating pulse summaries.

**Example context:**

```
Weekly revenue from our SaaS product. This chart tracks MRR (Monthly Recurring Revenue) 
from all paid subscriptions. Spikes usually indicate annual billing cycles. 
Drops may reflect churn or downgrades.
```

## How It Appears in Product

When viewing a Source or [Source Group](/admin/sources/source-groups), you'll see:

```
User Notes
Provide context about this chart to improve AI analysis quality. 
This context will be included in pulse summaries.

Describe what this chart shows, e.g.:
- "Weekly revenue from our SaaS product"
- "Daily active users by platform"  
- "Ad spend vs conversions for Q4 campaign"

~0 / 500 tokens
```

## Best Practices

<AccordionGroup>
  <Accordion title="Be specific">
    Good: "Weekly revenue from enterprise customers, excluding trials and refunds"

    Vague: "This is a revenue chart"
  </Accordion>

  <Accordion title="Explain anomalies">
    Note patterns the AI should expect:

    * "Spikes on Mondays due to weekend batch processing"
    * "Zero values on holidays when offices are closed"
    * "Quarterly drops reflect planned maintenance windows"
  </Accordion>

  <Accordion title="Define metrics">
    Clarify how metrics are calculated:

    * "LTV = Average revenue per user × Average customer lifetime"
    * "Active users = Unique logins in past 7 days"
    * "MRR includes all recurring subscriptions, excludes one-time fees"
  </Accordion>

  <Accordion title="Mention goals and thresholds">
    Help the AI understand significance:

    * "Target is 10% MoM growth"
    * "Alert threshold is 95% uptime"
    * "Below 5% is considered healthy churn"
  </Accordion>
</AccordionGroup>

## User Notes vs External Context

| Feature           | User Notes                    | External Context            |
| :---------------- | :---------------------------- | :-------------------------- |
| **Setup**         | Type directly in product      | Link external documents     |
| **Maintenance**   | Edit each source individually | Update document once        |
| **Collaboration** | Single user input             | Team can edit documents     |
| **Length**        | 500 tokens (\~375 words)      | Full document content       |
| **Best for**      | Quick descriptions            | Comprehensive documentation |
| **Sharing**       | Sources & Groups supported    | Sources & Groups supported  |

## Assignment Options

You can map User Notes at two levels:

* **Single Source**: The note applies only to pulses from that specific source.
* **Source Group**: The note applies to all sources within the group. This is ideal for describing general trends or shared goals across multiple charts.

## When to Use Each

### Use User Notes when:

* You need a quick description
* The context is specific to one chart or a small group
* You're testing what context helps most
* The explanation is short and simple

### Use External Context when:

* You have existing strategy documents
* Multiple sources share the same context
* Context needs team collaboration
* You want to maintain context in one place
* The documentation is comprehensive

<Warning>
  **Consider External Context First**

  While User Notes are convenient, external documents are often better because:

  * They can be updated without editing each source
  * Teams can collaborate on documentation
  * Context stays in sync with actual business strategy
  * Easier to maintain as your business evolves

  Think of User Notes as a quick fix, External Context as the robust solution.
</Warning>

## Tips for Writing Great Context

<Steps>
  <Step title="Start with what">
    What does this chart measure? Be specific about metrics and time periods.
  </Step>

  <Step title="Explain why it matters">
    Why should stakeholders care about this data? Connect it to business goals.
  </Step>

  <Step title="Note caveats">
    What should the AI know about limitations or edge cases?
  </Step>

  <Step title="Add context clues">
    What external factors might influence this data? (campaigns, seasonality, etc.)
  </Step>
</Steps>

## Example Contexts

### Revenue Chart

```
Weekly MRR (Monthly Recurring Revenue) from all active subscriptions. 
Excludes trials, refunds, and one-time setup fees. Spikes typically 
indicate annual plan conversions. Target growth is 10% MoM. Data 
updates every Monday morning after weekend batch processing.
```

### User Activity

```
Daily active users (DAU) measured as unique logins in past 24 hours. 
Includes all platforms (web, iOS, Android). Weekend dip is normal. 
Major product releases usually cause 15-20% spike in following week. 
Baseline target is 10,000 DAU.
```

### Campaign Performance

```
Q4 holiday campaign performance tracking ad spend vs attributed 
conversions. Includes Facebook, Google, and LinkedIn ads. ROAS target 
is 3.0x. Attribution window is 7-day click. Exclude December 24-26 
from analysis due to holiday shipping cutoff.
```

## Managing User Notes

You can manage all sources and their notes in the context settings.

<Button title="Manage User Notes" icon="sticky-note" href="/admin/settings/context?type=user-notes">
  Manage User Notes
</Button>

1. Navigate to the Source or [Source Group](/admin/sources/source-groups) detail page.
2. Find the **User Notes** section.
3. Click the text area and enter your description.
4. Changes are saved automatically.
5. New pulses will include the updated context.

<Note>
  Changes to User Notes take effect on the next pulse generation. Existing pulses are not retroactively updated.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Try User Notes" icon="edit">
    Add notes to one of your existing sources or groups
  </Card>

  <Card title="Set Up External Context" icon="link" href="/analysis/context/overview">
    Learn about linking external documents
  </Card>
</CardGroup>