| 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-resultsskill) - Visualizations prepared (use
creating-visualizationsskill) - 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:
Introduction & Thesis
- State the question or problem
- Present your key finding or recommendation
- Preview supporting evidence
Body & Supporting Arguments
- Present data findings that support your thesis
- Use visualizations to make patterns clear
- Address alternative explanations
- Cite data sources and methodology
Conclusion & Next Steps
- Restate key findings
- Articulate implications and recommendations
- Identify limitations and follow-up questions
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
---
## 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
{#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-visualizationsterminal formats for inline code examples - Include ASCII charts in whitepaper appendices
- Show sparklines for trend indicators
Image-based visualizations:
- Use
creating-visualizationsimage 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:
- Data Sources - Databases, APIs, file systems
- SQL Queries - Specific queries used in analysis
- Analysis Tools - Software and versions (DataPeeker, Python, R)
- Prior Research - Published papers or internal reports
- 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/tilmon/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/tilmon/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/tilmon/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/tilmon/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:
- Choose format based on audience (Phase 1)
- Structure narrative using essay or story patterns (Phase 2)
- Create content with marp/pandoc (Phase 3)
- Add citations and reproducibility documentation (Phase 4)
- Generate outputs for delivery (Phase 5)
Typical Usage Contexts:
exploratory-analysis→ Use presenting-data for final reportguided-investigation→ Use presenting-data to document findingshypothesis-testing→ Use presenting-data to publish resultscomparative-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