presenting-data

name	presenting-data
description	Component skill for creating compelling data-driven presentations and whitepapers using marp and pandoc with proper citations and reproducibility

Presenting Data

Purpose

This component skill guides creation of professional data-driven presentations and whitepapers. Use it when:

• Communicating analysis findings to stakeholders
• Creating executive summaries and detailed technical reports
• Documenting reproducible research with proper citations
• Building a presentation hierarchy: slides → whitepapers (drill-in capability)
• Referenced by process skills for final deliverables

Supports two complementary formats:

• Presentations (marp) - Slide decks for meetings, pitches, and executive summaries
• Whitepapers (pandoc) - Comprehensive documents with citations, cross-references, and academic formatting

Prerequisites

• Analysis completed with clear findings
• Query results documented and interpreted (use interpreting-results skill)
• Visualizations prepared (use creating-visualizations skill)
• Understanding of data sources, queries, and reproducibility requirements
• Clear communication goal and target audience identified

Data Presentation Process

Create a TodoWrite checklist for the 5-phase presentation process:

Phase 1: Analyze Audience & Purpose - pending
Phase 2: Structure Narrative - pending
Phase 3: Create Content - pending
Phase 4: Add Citations & Reproducibility - pending
Phase 5: Generate Outputs - pending

Mark each phase as you complete it. Document all presentation materials in your analysis directory.

---

Phase 1: Analyze Audience & Purpose

Goal: Understand who will consume your presentation and what decisions they need to make.

Identify Your Audience

Executive Stakeholders:

• Format: Slide presentation (5-10 slides)
• Focus: Key findings, business impact, recommendations
• Detail Level: High-level metrics, visual emphasis
• Tool: marp for quick, visual presentations

Technical Peers:

• Format: Whitepaper or technical report (20-50 pages)
• Focus: Methodology, reproducibility, detailed analysis
• Detail Level: SQL queries, statistical methods, data quality notes
• Tool: pandoc for comprehensive documentation

Mixed Audience:

• Format: Both (presentation + supporting whitepaper)
• Focus: Slides for overview, whitepaper for drill-in details
• Detail Level: Presentation hierarchy allowing progressive disclosure
• Tools: marp for slides, pandoc for backing documents

Define Communication Goals

What decisions will this presentation support?

• Strategic planning (high-level trends and forecasts)
• Operational changes (specific process improvements)
• Technical validation (methodology and reproducibility)
• Policy changes (compliance, risk, standards)

What actions should the audience take?

• Approve/reject a proposal
• Allocate budget or resources
• Change operational procedures
• Investigate further (drill into details)

CHECKPOINT: Before proceeding to Phase 2, you MUST have:

• Target audience identified (executive, technical, or mixed)
• Primary communication goal defined
• Desired audience action articulated
• Output format selected (presentation, whitepaper, or both)

---

Phase 2: Structure Narrative

Goal: Organize findings into a compelling narrative that guides the audience to your conclusions.

Use the 3-Paragraph Essay Structure

→ See frameworks/3-paragraph-essay.md for detailed guidance

The classic essay structure adapts perfectly to data presentations:

1. Introduction & Thesis

   • State the question or problem
   • Present your key finding or recommendation
   • Preview supporting evidence

2. Body & Supporting Arguments

   • Present data findings that support your thesis
   • Use visualizations to make patterns clear
   • Address alternative explanations
   • Cite data sources and methodology

3. Conclusion & Next Steps

   • Restate key findings
   • Articulate implications and recommendations
   • Identify limitations and follow-up questions

4. Bibliography & Supporting Documentation

   • Data sources and SQL queries
   • Reproducibility information (versions, timestamps)
   • References to prior research or methodology
   • Links to detailed whitepapers or repositories

Apply Narrative Structure for Data Stories

→ See frameworks/narrative-structure.md for storytelling patterns

Data presentations follow narrative arcs:

• Setup: Establish business context and question
• Conflict: Present the data challenge or pattern
• Resolution: Show findings and recommendations
• Call to Action: Define next steps

Outline Your Presentation

Create outline document: analysis/[session-name]/presentation-outline.md

For Presentations (Marp):

# Presentation Outline

## Slide 1: Title & Context
- Analysis question
- Time period and data sources

## Slide 2-3: Key Findings (Thesis)
- 3-5 bullet points with metrics
- Visual emphasis

## Slide 4-7: Supporting Evidence (Body)
- One finding per slide
- Include visualizations
- Reference methodology

## Slide 8: Conclusions & Recommendations
- Restate key findings
- Next steps
- Questions

## Slide 9: Reproducibility Notes (Appendix)
- Data sources
- Query locations
- Validation status

For Whitepapers (Pandoc):

# Whitepaper Outline

## Introduction (2-3 pages)
- Business context and objectives
- Research question
- Thesis statement

## Methodology (5-10 pages)
- Data sources and collection methods
- SQL queries and transformations
- Analysis frameworks used
- Data quality assessment

## Results (10-20 pages)
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data
- Visualizations and tables

## Discussion (5-10 pages)
- Interpretation of findings
- Comparison to prior research
- Limitations and caveats
- Alternative explanations

## Conclusions (2-3 pages)
- Summary of key findings
- Recommendations
- Future research directions

## References
- Bibliography (BibTeX format)
- Appendix: SQL queries
- Appendix: Data validation notes

CHECKPOINT: Before proceeding to Phase 3, you MUST have:

• Narrative structure selected (essay-based or story-based)
• Presentation outline created with sections identified
• Key findings and supporting evidence mapped
• Introduction, body, conclusion, and bibliography sections defined

---

Phase 3: Create Content

Goal: Write presentation content using appropriate tools (marp for slides, pandoc for documents).

Creating Slide Presentations with Marp

→ See tools/marp.md for detailed CLI usage and syntax

Marp transforms Markdown into professional slide decks. Use for:

• Executive summaries (5-10 slides)
• Meeting presentations
• Quick stakeholder updates

Basic Marp Syntax:

---
theme: gaia
paginate: true
footer: "DataPeeker Analysis"
---

# Q4 Sales Analysis
## Key Findings

---

## Data Source
- Database: `analytics_prod.sales_metrics`
- Query Date: 2025-11-25
- Period: 2024-10-01 to 2024-12-31

---

## Finding 1: Revenue Growth

- Total Revenue: $1.2M
- YoY Growth: +23%
- Top Region: West Coast

![width:600px](revenue-chart.png)

---

## Methodology

\```sql
SELECT
  DATE_TRUNC('month', date) as month,
  SUM(amount) as revenue
FROM sales_metrics
WHERE date BETWEEN '2024-10-01' AND '2024-12-31'
GROUP BY month
\```

---

## Conclusions

- Revenue exceeded target by 15%
- West Coast expansion successful
- Recommend continued investment

---

## Reproducibility

- Queries: `queries/q4_analysis.sql`
- Data validated: 2025-11-25
- Full report: [Technical Whitepaper](./whitepaper.pdf)

Generate Presentation:

marp presentation.md -o presentation.pdf

Creating Whitepapers with Pandoc

→ See tools/pandoc.md for detailed CLI usage and citations

Pandoc creates publication-quality documents. Use for:

• Technical reports (20-50 pages)
• Comprehensive analysis documentation
• Academic papers with citations and cross-references

Basic Pandoc Structure:

---
title: "Q4 Sales Performance Analysis"
author: "DataPeeker Team"
date: "2025-11-25"
institute: "Tilmon Engineering"
abstract: |
  This analysis examines Q4 2024 sales data, revealing 23% YoY growth
  driven primarily by West Coast expansion. Methodology, findings, and
  recommendations are presented with full reproducibility documentation.
keywords: "sales analysis, SQL, data analysis, reproducibility"
toc: true
lof: true
lot: true
---

# Introduction

This analysis addresses the question: What factors drove Q4 2024
sales performance? Using DataPeeker to analyze production database
records, we identify key growth drivers and provide actionable
recommendations.

# Methodology

## Data Collection

Data was extracted from `analytics_prod.sales_metrics` using:

\```sql
SELECT
  transaction_id,
  customer_id,
  region,
  amount,
  transaction_date
FROM sales_metrics
WHERE DATE(transaction_date) BETWEEN '2024-10-01' AND '2024-12-31'
ORDER BY transaction_date
\```

## Analysis Framework

Analysis followed established data quality frameworks [@jones2024]
and reproducibility standards [@smith2023].

# Results

![Q4 Revenue by Region](revenue-by-region.png){#fig:revenue}

Figure @fig:revenue demonstrates clear regional patterns.

# Discussion

Our findings align with previous research on seasonal trends
[@williams2024] while revealing new patterns in customer behavior.

# Conclusions

Three key findings emerge from this analysis:
1. West Coast growth exceeded projections
2. Customer acquisition accelerated in Q4
3. Average transaction value increased 12%

# References

Generate Whitepaper:

pandoc whitepaper.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -F pandoc-crossref \
  -s -V geometry:margin=1in \
  --toc \
  --number-sections \
  -o whitepaper.pdf

Integrating Visualizations

Use creating-visualizations component skill to create charts and diagrams:

Terminal visualizations:

• Use creating-visualizations terminal formats for inline code examples
• Include ASCII charts in whitepaper appendices
• Show sparklines for trend indicators

Image-based visualizations:

• Use creating-visualizations image formats (Kroki) for slides and whitepapers
• Generate Mermaid flowcharts for methodology sections
• Create GraphViz diagrams for data lineage
• Use Vega-Lite for statistical charts

Best Practices:

• Export visualizations as PNG/SVG for marp presentations
• Reference figure numbers in pandoc documents
• Include chart source data or generation code
• Document visualization choices in methodology

CHECKPOINT: Before proceeding to Phase 4, you MUST have:

• Presentation/whitepaper content drafted in Markdown
• Visualizations created and embedded
• SQL queries and code snippets included
• Narrative structure followed (introduction, body, conclusion)

---

Phase 4: Add Citations & Reproducibility

Goal: Document data sources, queries, and methodology to enable reproducibility and proper attribution.

Citing Data Sources and Queries

→ See formats/citations.md for BibTeX and CSL formats

Proper citation enables:

• Traceability to original data sources
• Validation of methodology
• Reproducibility by others
• Academic and professional credibility

Citation Types for Data Analysis:

1. Data Sources - Databases, APIs, file systems
2. SQL Queries - Specific queries used in analysis
3. Analysis Tools - Software and versions (DataPeeker, Python, R)
4. Prior Research - Published papers or internal reports
5. Methodology References - Statistical methods or frameworks

Example BibTeX Entries:

@misc{production_database_2025,
  author = {Tilmon Engineering},
  title = {Production Sales Metrics Database},
  year = {2025},
  url = {analytics_prod.sales_metrics},
  note = {Query timestamp: 2025-11-25 14:30 UTC}
}

@software{datapeeker_2025,
  author = {Tilmon Engineering},
  title = {DataPeeker: SQL Analysis Tool},
  year = {2025},
  version = {2.1.0},
  url = {https://github.com/example-org/datapeeker}
}

Documenting Reproducibility

→ See formats/reproducibility.md for comprehensive checklist

Reproducible research requires documentation of:

• Data: Source, timestamp, version, schema
• Queries: Full SQL text, execution time, row counts
• Environment: Tool versions, dependencies, configuration
• Process: Step-by-step methodology
• Validation: Data quality checks, cross-validation results

Reproducibility Section Template:

## Reproducibility Information

### Data Sources
- **Database**: `analytics_prod.sales_metrics`
- **Schema Version**: v2.3.1
- **Query Timestamp**: 2025-11-25 14:30:00 UTC
- **Records Examined**: 50,000 transactions
- **Time Period**: 2024-10-01 to 2024-12-31

### Analysis Environment
- **Tool**: DataPeeker v2.1.0
- **Python Version**: 3.11.5
- **Key Libraries**: pandas 2.1.0, plotext 5.2.8
- **Operating System**: macOS 14.6.0

### Query Repository
- **Location**: `github.com/example-org/analysis/queries/q4_sales.sql`
- **Commit Hash**: abc123def456
- **Execution Time**: 3.2 seconds
- **Rows Returned**: 50,000

### Data Quality Validation
- **Null Values**: 0.02% (within tolerance)
- **Duplicates**: 0 detected
- **Outliers**: 12 identified and documented separately
- **Cross-Validation**: Results match source system aggregate queries

### Reproducibility Instructions
1. Clone repository: `git clone github.com/example-org/analysis`
2. Install dependencies: `pip install -r requirements.txt`
3. Run analysis: `python scripts/q4_analysis.py`
4. View results: `analysis/q4-2024/01-findings.md`

CHECKPOINT: Before proceeding to Phase 5, you MUST have:

• BibTeX bibliography created with data sources
• SQL queries documented with execution details
• Reproducibility section added with environment info
• Citations inserted in text using [@citation_key] syntax

---

Phase 5: Generate Outputs

Goal: Compile final presentation and whitepaper artifacts using marp and pandoc.

Generate Slide Presentation (Marp)

Basic PDF Output:

marp presentation.md -o presentation.pdf

HTML with Speaker Notes:

marp presentation.md -o presentation.html

PowerPoint (Editable):

marp presentation.md --pptx -o presentation.pptx

With Custom Theme:

marp presentation.md --theme-set custom-theme.css -o presentation.pdf

Watch Mode (Live Preview):

marp -w -p presentation.md

Generate Whitepaper (Pandoc)

PDF with Citations:

pandoc whitepaper.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -s -V geometry:margin=1in \
  -o whitepaper.pdf

PDF with Cross-References:

pandoc whitepaper.md \
  --citeproc \
  --bibliography references.bib \
  -F pandoc-crossref \
  -s --toc --number-sections \
  -o whitepaper.pdf

Word Document (Editable):

pandoc whitepaper.md \
  --citeproc \
  --bibliography references.bib \
  --reference-doc=template.docx \
  -o whitepaper.docx

HTML for Web Publishing:

pandoc whitepaper.md \
  --citeproc \
  --bibliography references.bib \
  -s -c style.css \
  --self-contained \
  -o whitepaper.html

Presentation Hierarchy (Slides → Whitepapers)

Link from slides to detailed documentation:

# Conclusion

For detailed methodology and reproducibility:
→ [Technical Whitepaper](./whitepaper.pdf)
→ [GitHub Repository](https://github.com/example-org/analysis)

File Organization:

analysis/
├── q4-2024/
│   ├── presentation.md (marp source)
│   ├── presentation.pdf (generated)
│   ├── whitepaper.md (pandoc source)
│   ├── whitepaper.pdf (generated)
│   ├── references.bib (bibliography)
│   ├── queries/
│   │   └── q4_analysis.sql
│   └── visualizations/
│       ├── revenue-chart.png
│       └── regional-breakdown.png

Automation Script:

#!/bin/bash
# generate_deliverables.sh

# Generate presentation
echo "Creating presentation..."
marp presentation.md -o presentation.pdf

# Generate whitepaper
echo "Creating whitepaper..."
pandoc whitepaper.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -F pandoc-crossref \
  -s --toc --number-sections \
  -V geometry:margin=1in \
  -o whitepaper.pdf

echo "Deliverables created:"
echo "  - presentation.pdf (slides)"
echo "  - whitepaper.pdf (detailed report)"

CHECKPOINT: Final verification before delivery:

• Presentation PDF generated and reviewed
• Whitepaper PDF generated with citations and cross-references
• All visualizations properly embedded and sized
• Bibliography and references correctly formatted
• Reproducibility information complete
• Links between presentation and whitepaper working
• Files organized in analysis directory structure

---

Integration with Process Skills

Process skills reference this component skill when presenting findings:

Use the `presenting-data` component skill to create professional
deliverables from your analysis:
- Executive presentations (marp) for quick communication
- Technical whitepapers (pandoc) for detailed documentation
- Both formats with proper citations and reproducibility

When presenting analysis results:

1. Choose format based on audience (Phase 1)
2. Structure narrative using essay or story patterns (Phase 2)
3. Create content with marp/pandoc (Phase 3)
4. Add citations and reproducibility documentation (Phase 4)
5. Generate outputs for delivery (Phase 5)

Typical Usage Contexts:

• exploratory-analysis → Use presenting-data for final report
• guided-investigation → Use presenting-data to document findings
• hypothesis-testing → Use presenting-data to publish results
• comparative-analysis → Use presenting-data for comparison reports

---

Quality Checklist

Before considering presentation complete:

Content Quality:

• Clear thesis or key finding stated upfront
• Supporting evidence logically organized
• Visualizations effectively communicate patterns
• Conclusions tied directly to evidence
• Limitations and caveats acknowledged

Reproducibility:

• Data sources fully documented
• SQL queries included or referenced
• Tool versions and environment documented
• Execution timestamps recorded
• Reproducibility instructions provided

Citation Quality:

• All data sources cited in bibliography
• Prior research properly attributed
• Analysis tools and versions documented
• Citation style consistent throughout
• Links to repositories and queries working

Technical Quality:

• Presentation PDF renders correctly
• Whitepaper PDF has working cross-references
• Images embedded and properly sized
• Code blocks have syntax highlighting
• Math equations render correctly (if applicable)

Narrative Quality:

• Introduction establishes context and question
• Body presents evidence systematically
• Conclusion restates findings clearly
• Bibliography enables drill-in for details
• Overall flow guides audience to conclusions

Presentation-Whitepaper Hierarchy:

• Slides provide high-level overview
• Whitepaper provides comprehensive details
• Links between formats working
• Consistent terminology and metrics
• Both reference same data sources

---

Best Practices

DO:

✅ Start with audience analysis to choose format ✅ Use 3-paragraph essay structure for clear narrative ✅ Include SQL queries for reproducibility ✅ Cite data sources in bibliography ✅ Create both slides and whitepaper for mixed audiences ✅ Link from presentations to detailed whitepapers ✅ Document environment, versions, and timestamps ✅ Use creating-visualizations for charts and diagrams ✅ Version control both source markdown and generated PDFs ✅ Test reproducibility instructions before delivery

DON'T:

❌ Skip audience analysis - format should match need ❌ Present findings without methodology documentation ❌ Forget to cite data sources and prior research ❌ Generate PDFs without reviewing output quality ❌ Mix presentation styles (stay consistent) ❌ Overcomplicate slides with too much detail ❌ Omit reproducibility information ❌ Assume audience can recreate analysis without documentation ❌ Ignore cross-references and internal links ❌ Deliver without validating bibliography formatting