Series contents · Engineering and Delivery · 阅读中文版
At a review, someone presents a polished diagram: an input tensor passes through an operator, and the output returns to memory. A few convincing assembly lines make the page look complete.
Then someone asks, “Does that configuration field actually exist in the code?”
The room goes quiet. The field name was invented to explain the idea, but readers had already interpreted it as a hardware interface.
A technical document’s most misleading error is not always a bad formula. It can be different levels of evidence presented with equal certainty.
The route from formula to instruction has several layers
An operator description can distinguish at least five layers:
- Mathematical semantics: what should be computed.
- Tensor semantics: constraints on shapes, axes, broadcasting, and data types.
- Numerical representation: scales, zero points, rounding, and saturation.
- Lowering and configuration: how that information enters the target representation.
- Instructions and encoding: what is emitted and how fields occupy bits.
Establishing one layer does not establish the next. Knowing that Split can be expressed as several Slice operations does not prove that a target compiler performs that decomposition. An instruction enumeration does not prove that import, lowering, memory allocation, and code generation form a complete path.
The early notes repeatedly distinguished conceptual configurations, possible routes, and confirmed fields. Those qualifiers matter. They allow a document to support design discussion without posing as a delivery capability list.
Why does a small example need so many conditions?
Suppose a document says only:
1 | y = x - b |
A reader could interpret b as an equal-shaped tensor, a scalar, or a per-channel parameter. If the example covers only equal-shaped inputs but never says so, later implementations can grow around incompatible assumptions.
Now consider the quantized representation x = s × (q-z). When input and output scales differ, integer subtraction generally cannot be expressed as simply subtracting two stored integers. An example using raw integers and conveniently equal scales hides the very rescaling question that needs explanation.
A better example identifies operand roles, shapes, dtypes, quantization parameters, layouts, and which values are known at compile time. These details tell readers what the example demonstrates and what it leaves unproven; they are not decoration for a table.
Similar operation names do not justify merging their specifications
“Max” may mean elementwise comparison, reduction over an axis, or part of sliding-window pooling. ArgMax returns an index and introduces tie rules and index width.
Similarly, inference-time BatchNorm can fold fixed statistics into constants. Normalization that computes statistics from the current input cannot mechanically reuse that constant-parameter model. Calling both “normalization” does not give them identical runtime dependencies.
A reliable document identifies boundaries hidden by names:
| Ambiguous term | Question that must be answered |
|---|---|
| max | Compare two tensors, or reduce along an axis? |
| mean | Arbitrary-axis reduction, or a sliding window? |
| power | Ordinary exponentiation, or a sign-preserving power transform? |
| norm | Statistics from constants, or from this input? |
| reshape | Change a view, or physically move data? |
| supported | Defined, importable, or executable end to end? |
This table is a teaching summary, not a product support matrix.
Example addresses should not masquerade as resource constraints
Documents often assign tidy addresses to small tensors to make a memory diagram readable. A reader may mistake that layout choice for a real alignment requirement.
Use symbolic addresses and an alignment parameter A first, then explain that a numeric example is one possible arrangement. If alignment is unconfirmed, leave that uncertainty explicit. A casually chosen number should not become an interface promise.
Likewise, a tensor containing only a few elements may still require padding. Narrow input and output integers do not imply an equally narrow accumulator. Keeping physical byte layout separate from mathematical tensor description makes later discussions of capacity and address advancement possible.
How can a document help discover a bug?
Review an example in three rounds.
First, examine the mathematics. Are the inputs, outputs, and boundary conditions consistent? Does reshape preserve element count? Can convolution output size be derived from its attributes? Is the rule for retaining reduced dimensions explicit?
Second, examine representation. Can the quantized range cover the output? How does the zero point affect padding values? Can the index type represent positions along the target axis? Is the local buffer large enough?
Third, examine implementation evidence. Where does the conversion occur? Where do configuration values come from? Which attribute combinations do tests cover? Without a complete implementation, stop at a candidate design instead of drawing definite final machine code.
These checks can expose ambiguity before implementation or stale documentation afterward. Every page need not answer everything. Every definite claim should have evidence at the level it claims.
“To be confirmed” needs a condition for resolution
An indefinite question mark eventually turns a document into an archaeological site. Convert unknowns into answerable questions:
- Which physical dimension represents this semantic axis in the current layout?
- Is the quantization multiplier generated at compile time or computed at runtime?
- Does one descriptor carry multiple output addresses, or are several operations emitted?
- If no dedicated instruction exists, is there a verified composition using other operations?
- Does this test inspect IR only, or execute the target program?
When code or tests answer a question, update that section rather than changing the whole page from “draft” to “supported.” Implementation maturity advances by subproblem; documentation should express the same granularity.
Why documentation needs regression checks too
An example path that goes up one directory too far can stop a reader before any algorithm runs. A removed option left in a README creates a fictional entry point. Once documentation ships with installed artifacts, links and required pages become part of package completeness.
The reviewed history included tiny path corrections alongside broad operator examples and user-facing documentation work. Their technical value differs, but both belong in the engineering account: one restores reproducibility of an example; the other organizes semantics and implementation evidence.
Suggested checks cover references, relative paths, command options, formula assumptions, and support boundaries. A conceptual workflow should be checked for logical consistency rather than presented as directly runnable code.
Honesty does not make a story dull
A good question can be more engaging than a row of confident claims: “Why does changing only the output scale require different parameters for what looks like the same subtraction?” “Why might an operation with equal input and output shapes still introduce a copy?” These questions guide reasoning without inventing missing facts.
Useful technical documentation does not always look finished. It makes the next verification step clear, turning unknowns into boundaries and boundaries into questions that can be discussed and resolved.
Series contents · Previous · Next
If you like this blog or find it useful for you, you are welcome to comment on it. You are also welcome to share this blog, so that more people can participate in it. All the images used in the blog are my original works or AI works, if you want to take it,don't hesitate. Thank you !