Technical Writing and Documentation Questions

Assumptions & Methodology: We attribute closed sales to all tracked digital touchpoints that occurred within a 30-day attribution window prior to the opportunity close date (default window; configurable per campaign). We apply a linear multi-touch weighting where each touch within the window receives equal fractional credit; for stakeholders wanting recency sensitivity we can switch to time-decay or last-touch on request. Data is joined deterministically by user identifiers (CRM lead_id/customer_id and hashed email) and session identifiers where available, with event-level joins between CRM opportunity records, web analytics session logs, ad click logs, email engagement events, and the customer master; timestamps are used to filter touches into the attribution window. Missing or empty UTM parameters are handled by (1) attempting to infer channel from referrer and landing page, (2) falling back to a canonical “(direct/unknown)” bucket, and (3) flagging records with inferred values so they can be excluded in sensitivity analyses. We deduplicate events by session_id + timestamp to avoid double-counting. Limitations: this approach misses offline and untracked touchpoints (sales calls, in-person events) and is subject to cross-device fragmentation and cookie deletion which can undercount true touch frequency. Finally, equal weighting can mask the varying influence of creative, frequency, and contextual factors—treat results as directional and validate with experiments (UTM-tagged campaigns or holdout tests) before major budget shifts.

Escalation plan (summary)

• Triage (0–15m): Identify failure cause (ETL, data source, report server). Owner: me — check job logs, data warehouse load status, and BI service health.
• Contain (15–45m): If ETL failed, re-run incremental load or rollback to last successful snapshot; if report rendering fails, restart BI service and force cache refresh. Owner: me + Data Engineering on-call.
• Mitigate (45–90m): Prepare contingency artifacts (cached numbers, CSV extracts, one-slide summary) and validate key KPIs against source systems. Owner: me.
• Communicate (continuous): Send status updates at 30m, 60m, and when resolved. Owner: me.
• Post-incident (by EOD): Root cause analysis and preventive actions (tests, alerts, runbook). Owner: Data Eng + BI.

Stakeholder email (to CEO/CFO)
Subject: Executive Report Failure — Immediate Mitigation & Contingency

One-sentence summary: The scheduled executive report failed this morning due to a data pipeline/rendering error and is unavailable for the board meeting.

Immediate steps I’m taking:

• Re-running ETL and restarting the BI service; validating key KPIs against source systems.
  Contingency artifacts available in 30–45 minutes:
• Cached KPI spreadsheet, CSV extracts, and a one-slide summary of revenue, margin, and cash metrics.
  Follow-up: I’ll update at 30 minutes and confirm resolution within 90 minutes. Owner: [Your Name], BI Analyst (pager: xxx-xxx-xxxx).

1. Axis labels: Use short, noun-based labels (no verbs). Capitalize Title Case. Add units in parentheses: Revenue (USD), Customers (count).
2. Axis units: If values are scaled, show unit on axis label and a small scale suffix on the chart (e.g., Revenue (USD, thousands) and “k” on ticks).
3. Number formatting: Use comma separators for thousands. Show no trailing zeros for integers; use one or two decimals only when meaningful (e.g., 12,345 or 12.3k).
4. Rounding rules: Round to the display precision: thousands (k) — round to 1 decimal (12.3k). Millions (M) — round to 2 decimals only for small values (1.02M).
5. Currency: Always include currency code in label (Revenue (USD)). Don’t mix currencies on one chart. Use currency symbol in tooltips ($12,345.00) when space permits.
6. Date granularity: Match axis granularity to range: <2 months = daily, 2–24 months = monthly, >24 months = quarterly or yearly. Label formats: Jan 2025 (monthly), Q1 2024 (quarterly).
7. Tooltip text: Be concise, full sentence optional: “Revenue (USD): $12,345 — 23% YoY”. Include exact unrounded values and context (period, comparison).
8. Abbreviations & legends: Define non-obvious abbreviations in a legend or hover. Keep abbreviations consistent across dashboards.
9. Accessibility: Ensure contrast meets WCAG; provide exact values for screen readers (aria labels or data table).
10. Consistency: Apply these rules across all enterprise dashboards; document exceptions.

Examples:
Correct: Axis label — Revenue (USD, thousands); tick — 12.3k; tooltip — Revenue (USD): $12,345.67; Period: Jan 2025.
Incorrect: Axis label — “Sales $” (no unit scale), tick — 12345, tooltip — “12k” (no currency code or exact value).

Purpose
This pipeline produces the daily "Daily Sales" report (sales by SKU, region, channel; daily totals; returns) and refreshes downstream Looker/Power BI dashboards every morning so stakeholders have up-to-date revenue metrics.

High-level architecture (text)
Source DBs (OLTP, POS CSVs) → Airflow DAG (ingest & transform orchestration) → Raw tables in Analytics DB → dbt models (staging → marts → reports) → Analytics DB (final tables) → BI tool (scheduled extract/refresh)

Run schedule

• Airflow DAG: daily at 04:00 UTC
• dbt run within DAG: runs after ingestion; finishes ~04:30 UTC
• BI dashboard refresh: 05:00 UTC

Preconditions

• Source connections reachable (VPN, credentials)
• Sufficient warehouse credits/quota
• No upstream schema changes without notice
• Latest POS CSVs delivered to S3 / network path

Dependencies

• Airflow (composer/managed) + DAG: dags/daily_sales.py
• dbt project: /dbt/daily_sales, profiles.yml configured
• Postgres/BigQuery/Snowflake analytics DB
• S3 (or file share) for CSVs
• Secrets manager for credentials
• BI tool scheduled refresh

Failure-handling checklist

1. Check Airflow DAG logs for failed task and timestamp.
2. If ingest failed: verify source availability, file presence, and network; re-run ingest task.
3. If dbt failed: run dbt test locally or check dbt run error; fix failing model or seed; consider reverting recent schema changes.
4. If warehouse resource errors: check quota/credits and resume or request more.
5. If BI refresh failed: check DB table freshness and BI connector logs.
6. Escalate if unresolved after steps below.

How to rerun jobs manually

• Airflow UI: Trigger DAG daily_sales for desired execution_date; for a single failed task: clear and re-run task.
• CLI (if needed):
  • dbt: cd /dbt/daily_sales && dbt run --models report_daily_sales --profiles-dir ~/.dbt
  • Airflow CLI: airflow dags trigger daily_sales --conf '{"run_reason":"manual-rerun"}'
• Validate: run dbt test and spot-check row counts / CI tests; confirm BI dashboard refresh at 05:00 or trigger manual refresh.

Primary contacts

• BI Owner: Alice Chen (alice.chen@company.com) — reports & metrics owner
• Data Eng Lead: Marco Rivera (marco.rivera@company.com) — pipeline & Airflow
• On-call rotation: data-platform-oncall@company.com (pager duty link)

Notes

• Include run_id and execution_date in any incident report.
• If schema change is suspected, pause DAG and notify Data Eng before reruns.

Subject: Urgent: Missing customer-level mapping for Weekly Retention Report — needed by Mon 24 Nov 2025 10:00 AM PT

Hi Data Engineering team,

Context: Our Weekly Retention report (used by Growth and Product) fails to join customer activity to segmentation attributes. Without the customer-level mapping, retention metrics by cohort are incomplete and misreported.

Missing table/fields:

• dim_customer_mapping (expected source)
  • customer_id (PK)
  • segment_id
  • acquisition_channel
  • effective_date
  • status

Example problematic row (expected vs. found):

• Expected: customer_id=12345 | segment_id=LOYAL | acquisition_channel=PaidSearch | effective_date=2025-11-20 | status=active
• Actual: customer_id=12345 | segment_id=NULL | acquisition_channel=NULL | effective_date=NULL | status=NULL

Hard deadline: Please provide the complete/updated dim_customer_mapping table (or a patch with the missing fields populated) by 10:00 AM PT on Monday, 24 Nov 2025.

If data is not available by the deadline, I will:

1. Publish the report using last-known mappings and add a clear footnote about potential inaccuracies, AND
2. Escalate to the Data Platform lead and notify report stakeholders of the data gap and expected timeline.

If you need more context or a sample query to validate, I can share immediately. Thanks for the quick help — this drives key decisions for next-week campaigns.

Best,
[Your Name]
Business Intelligence Analyst