Data teams receive a particular kind of message more often than any other: “the numbers look off.” It is honest, urgent and almost impossible to act on. This explainer describes how to turn that sentence into a data pipeline question that can actually be answered, whether you are an analyst reporting a discrepancy or an engineer asking a peer to look at a failing job. The method is the same in both directions, and it is simpler than it sounds.
Why “the numbers look off” stalls
A data pipeline is a chain of steps: sources, extraction, transformation, loading, and finally a report or a model. When someone says a figure is wrong, the responsible engineer faces a search across that whole chain. Which table? Which time range? Compared with what? Without answers, the first hour of work is detective work on the question itself rather than on the data.
A precise message removes that hour. It names the dataset, the period, the figure you saw and the figure you expected, and it explains why you expected it. The last part matters most, because your reasoning reveals the assumption that may be mistaken, either yours or the pipeline’s.
The six parts of a well-formed data question
1. The goal
Say what the data is for. “I am reconciling weekly revenue for the finance review” tells the reader which level of precision matters. A discrepancy of a few rows may be irrelevant to a trend chart and critical to a ledger match.
2. What you already checked
List the checks you ran: row counts at source and destination, a sample of raw records, the last successful run time. Each item removes a branch from the search and shows the reader you have done your share.
3. What you expected
State the expected value and its basis. “Yesterday’s order count should match the operational system within a small margin, because the load is a straight copy.” That sentence reveals the contract you believe the pipeline honours.
4. What actually happened
Report literal results. Paste the exact error text, the exact count, the exact timestamp. Paraphrases such as “it failed weirdly” hide the very detail a specialist would recognise instantly.
5. The smallest example
Find the minimal slice that shows the problem: one customer, one day, one partition, ten rows. Reducing a billion-row mismatch to a single record that is present upstream and missing downstream turns a vague investigation into a targeted one.
6. What changed recently
Pipelines rarely break on their own. A schema edit, a new source, a changed schedule or a modified filter is often involved. Even “nothing that I know of” is useful, because it narrows suspicion towards upstream systems you do not own.
A worked contrast
Consider two messages sent about the same fault. The first reads: “The daily sales table is wrong, please fix.” The second reads: “I am preparing the Monday summary. I compared the daily sales table with the source system for one store and one day. I expected 212 transactions, because the load copies them one for one, but the table holds 198. The fourteen missing rows all share a refund flag. Nothing changed on my side, and the last run completed normally.” The second message nearly contains its own diagnosis, and the answer is likely to be a one-line filter fix.
Where community examples help
Learning to write these messages is faster if you read many of them. Debug School is a community website where members publish posts on IT operations topics, including DataOps, and it makes a useful reading list for seeing how different people describe their problems. Treat it as a place to study structure and tone, then bring that discipline back to your own team channel.
Making it a team habit
Questions improve when the surrounding practice supports them. If your pipelines expose run history and row counts clearly, writing the “what I checked” section becomes quick. Our overview of how streaming reports survive broken data flows explains the kinds of signals worth surfacing, and the collection of hands-on DataOps examples for data teams shows how those signals are used in everyday work.
A simple team convention helps too. Add a short template to your request form or channel topic with the six headings above. People will skip a heading when it does not apply, but the prompt alone raises the quality of most messages. Over a few weeks, you will notice fewer clarifying replies and shorter resolution times, and newcomers will learn the standard by example instead of by correction.
Questions to ask before you send
Read your message once as if you were the engineer receiving it on a busy afternoon with no background. Could you tell which system is involved? Could you copy a query or an identifier and begin? Would you know what outcome the sender wants? If any answer is no, add one sentence. Also consider whether a screenshot of a chart really helps, or whether the underlying numbers in text would be easier to search and compare. Text is quicker to quote, and it survives being forwarded to a third person who joins the thread later.
A closing thought on tone
Precision is not coldness. A well-formed question usually reads as courteous because it respects the reader’s time and shows what you have already tried. It also protects relationships: when a defect turns out to be your own misunderstanding, a clear message makes the correction painless for everyone. Ask well, and the data will tend to answer faster.
