A Practical Guide to Notebooks

Getting started with Notebooks

Notebooks are your analytics lab notebook – a place where you can document your findings, share insights with your team, and maintain context throughout your investigations. Let’s explore how to use them effectively.

Creating your first notebook

1. Open the Notebooks tab in your TelemetryDeck dashboard
2. Click “Create New”
3. Give it a clear, descriptive title
4. Start writing your analysis using markdown

Adding charts to your notebook

The easiest way to add charts is using the “Copy TQL” button:

1. Create your chart in the TelemetryDeck Dashboard
2. Click the “Actions” menu
3. Select “Copy TQL”
4. In your notebook, create a code block marked as tql and paste the query:

```tql
{
  // Your chart's TQL query will be here
}
`` `

You can customize how your data is displayed using the displayMode value in your TQL:

• lineChart - Perfect for trends over time
• barChart - Great for categorical comparisons
• pieChart - Best for proportional data
• table - Ideal for detailed breakdowns
• funnel - Essential for conversion analysis

Using Markdown effectively

Notebooks support all standard markdown features:

• Headings (#, ##, etc.) – Structure your analysis into clear sections
• Lists (- or 1.) – Break down steps, findings, or requirements
• Code blocks (```) – Share TQL queries or technical details
• Images (![Alt text](image-url)) – Add screenshots or diagrams
• Blockquotes (>) – Highlight important insights or tips
• Tables – Compare data or list requirements

Putting it all together: a real-world example

Now that we’ve covered the basics, let’s see how notebooks work in practice. We’ll walk through an example of analyzing an app’s Onboarding flow, showing how notebooks help maintain context long-term.

Setting up the analysis

1. Define the Question

   # Onboarding flow analysis
   Question: How well does our app convert installations into paying customers?
   Hypothesis: The welcome window might be causing issues due to its similarity to Xcode's welcome screen.

2. Create the Funnel Chart

   • Use the dashboard to create a funnel chart
   • Click “Copy TQL” to get the query
   • Add it to your notebook with context:

   ## User journey analysis
   Let's track the complete user journey from installation to first successful value delivery:
   
   <paste TQL here>

3. Document Findings

   ## Initial results
   - 80% of users proceed past welcome screen
   - 55% complete setup step ⚠️
   - 80% convert after setup
   
   Key Insight: Welcome window isn't the problem. The real bottleneck is the setup step.

4. Plan Next Steps

   ## Next investigation
   To understand why users drop off during setup, we need to track:
   - [ ] `Onboarding.SetupStep.started` - When users begin the setup process
   - [ ] `Onboarding.SetupStep.completed` - When users finish setup
   - [ ] `Onboarding.SetupStep.abandoned` - When users leave without completing
   - [ ] `Onboarding.SetupStep.duration` - How long users spend in setup

Maintaining context over time

The real power of notebooks becomes apparent during long-running investigations. As you wait for new data, your notebook serves as a living document that:

1. Preserves Your Thinking – Document your hypotheses/assumptions
2. Tracks Progress – Note what data you’re waiting for and why
3. Prepares for Analysis – Set up charts that will show data when it arrives
4. Shares Knowledge – Help team members understand the context

This approach ensures you can pick up right where you left off when new data arrives, rather than starting from scratch.

Common use cases

Notebooks excel in several scenarios:

Performance Investigation: When tracking down issues, combine error logs with performance metrics in one place. Document your hypotheses, track implementation progress, and update findings as new data arrives.

Team Communication: Create weekly product health reports or onboard new team members by showing your notebooks. The combination of live charts and explanatory text makes it easy to convey complex insights.

Feature Analysis: Compare user behavior across versions or track feature adoption over time. Notebooks help you maintain context throughout the analysis, from initial hypothesis to final implementation.

Long-Running Investigations: Perhaps most importantly, notebooks help you maintain momentum during investigations that span weeks or months. Document what you’re waiting for, prepare your analysis structure, and dive back in as soon as new data arrives.

Ready to level up your analytics workflow? Open the Notebooks tab and start exploring your data in a more structured, insightful way now!

Related resources