You're going to get a lot of "don'ts" here; we've all been burned by lackluster datasheets before. But a good datasheet isn't superlative, it is merely adequate; complete. It's much harder to say what all has to go in one (and, obviously: it depends). Harder still to compose one from scratch: it's a particular form of communication, and one develops a skill for it, as with any other. In particular, you can wrack your brain for every possible thing you can think of, and still come up short -- the effort to get some review will be greatly rewarded. See what a customer really needs to know, to use your part!
The following is in the context of an IC datasheet; granted you might not be writing one of those, but likely you might be doing something similar enough. For example, you can view a PCB as an integrated circuit itself, and you should avoid talking about things within the board (that you may also wish to protect for IP reasons*), but do talk at length about what the pins are doing.
*Note that PCBs are a bit harder to protect than ICs; which aren't all that easy to protect by themselves -- several people/groups online are decapping and photographing chips these days! But any kind of measure that makes it harder to figure out, is still a step. For example, open-frame versus potted module. It's easy enough to x-ray a potted module, and not hard, merely tedious to excavate down into it. But that's also the basic level of effort that must be applied by anyone wishing to reverse-engineer it. For someone that just wants to use the thing, it's a literal black box.
Another reason is more mundane: avoid talking about what's on the PCB, because its design (component selection, placement, etc.) may change as bugs are found, specs improved, or parts substituted. Do be mindful of what your complete interface consists of; it's not just a description of electronic (pin) behaviors, but mechanical outline, thermal output, etc. as well. If you need to equip the module with a heatsink, for example, beware that someone will likely use that as a mounting plane as well as cooling. Try to avoid changes which break these features.
And, even if it's not electronic at all, I would still want to see similar things. Say in a pneumatic device, how much pressure, volume, flow rate / restriction, etc. does it have, under whatever conditions? Actuation force (to overcome friction, detents, etc.)? AC properties (acoustics) might not be so easy to cover (e.g. resonances of internal spaces, parts, connecting lines, etc.), but enough to give a basic operation, on/off, propagation delay, etc. time might be worthwhile (e.g. restriction * volume --> pneumatic time constant, or something like that).
That said, the things that I can think of:
1. Headline page
Says what it does, in plain language. Inevitably the domain of marketing wank, but there's always hope that a Good Datasheet is informative and concise here. Usually includes part number, product picture or drawing; maybe ordering options, example circuit/application, some characteristic to boast about (low distortion? high efficiency?), etc.
Avoid cover sheets from corporate acquisitions (onsemi), and addenda with oddly shaped pages (TI's part listing insert). (Is it really so hard to reformat the originals and run off new copies? Well yes, it might; keep the tools and procedures for doing that, well recorded (internally) as well!)
Table of contents optional. Follow the usual form and it shouldn't matter much; that said, worthwhile when the sheet is long (20+ pages?) and reading is digital (use hyperlinks!).
2. Data
- Absolute maximum ratings
- Mechanical dimensions and weight
- Thermal ratings/characteristics
- Regulatory approvals
- Recommended operating conditions
- Characteristics (DC, AC, min/typ/max)
- Characteristic curves (typ; min/max appreciated!)
Ratings should include current limits for when voltages beyond the limits are applied. For example: if a pin says -0.3 to VDD+0.3V, it's probably got diode clamps between VSS and VDD; how much current can I deliver into that, and for what purposes?
Example: 74HC logic is fine with a few mA at the input pins, but activation of ESD diodes causes minor current flow into nearby structures: including to the opposite rail (about half the applied current!), neighboring pins (small %), and maybe internal structures as well, creating a risk of corrupting internal state. At high currents, CMOS latchup occurs (typically 100mA+). MCU datasheets, typically say a few mA is acceptable on digital pins, but 0mA for "5V tolerant" types, or analog inputs (where the injected current would corrupt the state of the sensitive analog circuitry nearby -- ADC, AC, etc.).
Some notes whether the ESD is handled by clamp diodes, zeners or snapback diodes may be handy. For example, "5V tolerant" logic usually shows a zener at the input (e.g. 74LVC family), so is okay for any voltage within ratings independent of VDD, and probably not good for much current. Whereas if it's a snapback or thyristor type, any injected current will cause it to latch on and likely brown out the whole chip. Sometimes you see chips with the same modest ESD rating (4-6kV) on all pins, and they are probably using clamp diodes into a single common ESD structure (even for the logic pins that might not need it; why not, right?). Others, you see different ratings, like a minimal 1-2kV for logic and 8-15kV for interface (e.g. RS485 transceivers). Clearly they're using two different methods.
You don't need to be so particular (this is getting dangerously close to actual implementation!), but take this as example of what can be inferred from certain ratings, and consider whether you want to give a bit more detail about them, whether as ratings, characteristics, or more informally as discussion.
A good example of this is MCP6561:
https://ww1.microchip.com/downloads/en/DeviceDoc/MCP6561-1R-1U-2-4-1.8V-Low-Power-Push-Pull-Output-Comparator-DS20002139E.pdfAbs. max. shows voltages and currents, and in particular, gives an oddball limit of -1 to VDD+1V. A section of discussion is linked. Apparently the bottom limit is clamp diodes (surprising given the -1V limit), but the top limit is not (?!), and a recommended solution is provided (add clamp diodes externally).
3. Discussion
A block diagram, and basic explanation of device operation. Get as detailed as you can. So, probably stopping short of whatever IP you need to protect, but describe at least pin functions, voltages/currents, and behaviors. Your device is a black box, accessible through its pins and whatever other interface you've defined (including implicitly*).
*See
Hyrum's law. Note that, if your policy is to support interfaces defined in the datasheet (leaving undefined aspects unsupported, subject to change over time -- may break some customers' applications), you have the perverse incentive to document as little as possible, potentially breaking as much as possible. Balance this with an understanding of core features your customers require. (This generalizes much further than software or hardware: plausible deniability is a staple of bureaucratic and political interfaces, too!)
Older TI datasheets (and various others) used to show pin equivalent circuits, including ESD, and usually up to the first internal transistor or two (at which point, internal behavior can more or less be ignored with respect to pin V/I characteristics). Or for simple ICs, an equivalent, or even full, schematic (e.g. uA741's schematic is well known) may be reasonable.
4. Application
Provide design equations, with worked examples, of how to use your device in a typical circuit/system. TI's been quite good about this in the modern era; they've even added application sections to very old datasheets, TL494 for example. Mind, they've not been so great at explaining/justifying/proving the nature of those equations; such is usually out of scope for this kind of section (but could well be explained in an application note), but the consequence is not knowing what assumptions/approximations those equations are based on, so, how applicable they are in general.
Indeed, a recent thread here, shows the disconnect between general SMPS appnotes and particular datasheets; the underlying mechanisms aren't well explained, leading to confusion between different types of control and operation.
5. Back Matter
Anything that's additional, important to know (if it's not important,
it doesn't belong in the datasheet!), but not eclipsed in priority by the above. Examples: programming manual; package drawings; ordering information; quality information; legal disclaimers.
You might put Programming above Application for example, that would be fine (and happens often enough, I think).
And then in turn, those sections need to be thorough. Programming needs to document protocol, how to access registers, and then what those registers are (description, bits/values, interactions with other registers..). I'm fond of e.g. ATMEGA328 as an example: granted this is a whole MCU, but the peripheral sections are self-contained, include a reasonably complete description, document bits in all the registers*, and often give code examples. (The, uh---I haven't looked at 328P in a long while, but I think it's in the classic family? I recall asm and C examples in the '32 at least. Whereas I've worked more recently with XMEGA and DA series parts, which do not provide code examples. This is unfortunate, as the names given in the header aren't always obvious, and listing them in the datasheet would be convenient.)
That's another thing that's nice to give, and can be in the datasheet if you like: headers and other machine-readable data. Occasionally you'll see transistors, op-amps, etc. (mostly simple stuff like that) with SPICE models given right there. Very nice.
*If you're curious: almost all unused bits, reserved addresses, etc. read 0 (or whatever the default is), and have no effect, on a given device in the AVR family. Every bit that I've checked, anyway (but I've not done a comprehensive test, say of all bits on a particular device). I think they document these as a matter of, in relation to other products in the family -- for your own good, so your code can be a bit more portable between them, when you obey these aspects of the interface (setting default/ignoring unused bits/reserved registers). This is interesting, because you might assume some families are the same die with various options merely disabled, but perhaps still accessible if you try. And even if they don't do anything, maybe that's free storage space or something. I don't know about MCUs generally; apparently some CPUs and GPUs can be unlocked (at your own risk!). I have however seen undocumented registers in an LCD before (didn't seen to do anything, though).
Other Comments
DC characteristics:
Anything you'd measure with a DMM -- static voltages and currents. Can include internal signals, when there's a signal path and behavior to reach them (e.g. the error amp of UC3843 compares to an internal 2.5V reference, which has the effect of holding V(FB) at the same value when the loop is closed and stable). Do not include internal signals that are shown behind undefined ratios, used for entirely internal purposes, etc. Basically, if there is some way for me to know this exists, it should be documented; and if not, then not!
The tricky edge case might include stuff like current consumption. Maybe your internal signal is at some random ass voltage so, as mentioned, it doesn't matter; but say it happens to draw a corresponding current, while everything else in the chip/board is reasonably stable. One could therefore read that signal anyway, due to the change in supply current. Should that be part of the interface? Probably not, but maybe someone will try anyway. You have to think creatively and strategically about how things might be used, and misused, and consider how much of that you want to leave in, hint at, or avoid.
AC characteristics:
Anything that varies with time. Frequency response, transient response (e.g. propagation delays, rise/fall times), noise, etc. Note that things like input thresholds, you might not be able to test without a signal (e.g. hysteresis comparator), but the levels themselves are still ideally DC so belong in that section. Include timing diagrams for sequential interfaces. If things vary with other conditions (like pin capacitance vs. voltage), put that in somehow; fully specifying it might be a pain but a typical characteristic curve would be great (e.g. MOSFET capacitances depend on Vds, with one spot check given in the table, and a full curve in the plots section).
Input leakage / bias current:
An all-too-common omission. Just to reiterate: every pin must be defined, otherwise the user has no way to know how much resistance for example is acceptable to bias a pin. Have seen more than a few e.g. switching regulators, where the input (enable or feedback) pin bias is undefined, leaving me to rely on, say, typical (application) values instead -- and when they pick stupendously low resistances like 1k for the feedback divider, I'm left to ponder what the hell is going on. (Most often, it's irrelevant, and they could've used 100k resistors instead -- materially increasing efficiency at low currents, even!
)
This post:
I'm sure this can go on forever. It's... well, a datasheet for datasheets, as it were.
And, so, subject to the same limitations: I've omitted things, I've included irrelevant things, it's not well structured (would the illustrative examples be better placed down here in Comments, or inline as I've done?), and most of all it makes no reference to standards or other authoritative publications (I've only used example references). You should at least get some degree of review (contrasting with previous posts, and replies in turn correcting these).
A lot of these things are specified in JEDEC, JESD, IEC, etc. standards that aren't freely available, nor well known outside of IC mfgs; and respectively for other product types / markets. Some of which specify the ways in which parameters are to be measured; others concerning the documentation itself. So, I don't even know exactly what all motivates a typical datasheet, other than tradition, but that is something you may wish to research in greater depth, to understand where it comes from, why everyone does it that particular way.
Tim
Home
Help
Search
Login
Register
