On better datasheets
In 1998, Raymond Dewey of Allegro Microsystems compiled a series of his articles into “A Complete Guide to Data Sheets”. In an enviable writing style in its conciseness and punchiness he criticises companies who fail to author good datasheets.
Regrettably Dewey’s document aged well as little has improved in 20 years. I agree with Dewey’s analysis: manufacturers treat datasheets as marketing material; datasheets represent the face of the company; bad datasheets erode manufacturers’ credibility; engineers deeply familiar with the component are not significantly involved in authoring datasheets; and, technical documentation is a form of contract that ‘promises’ that the device will operate as described under specific conditions or limits (although in practice it's almost impossible to prove who's at fault).
Dewey writes:
A good data sheet allows the reader to accurately specify and purchase the exact product the reader needs without any other assistance. Even a barely acceptable data sheet should still allow the reader to make an intelligent decision as to whether or not the product should be further considered for a specific application. In general, data sheets are not read but are only referred to; engineers want/need hard facts about performance and specifications.
Electronic components are opaque and tiny. Our view into their insides come from the manufacturers. Primary source is the datasheet, and sometimes a user-guide. Secondary sources are application notes and white papers. Further sources are distributors, application engineers, online forums, friends, and notes scribbled in a notebook left behind by a retired colleague.
Dewey provides examples of disorganised, inconsistent, incomplete, and confusing data present in datasheets. This is because from the manufacturer’s point of view the datasheet’s primary aim is to ‘win the socket’ — get an engineer to commit the component into a design. That’s why Marketing is in charge and why ‘specsmanship’ seems essential: highlight the best and hide the rest. After winning the socket manufacturers rely on high switching costs while ignoring the impact of negative experience that may come later: previously very optimistic distributors, fresh errata, incomplete data, wrong data, etc. This is so obviously short sighted.
Dewey ends with defining good datasheet-authoring practices for Allegro, his employer:
1. The data sheet needs to convey an accurate and honest picture of Allegro’s technical leadership and expertise – the data sheet is a subliminal communicator of corporate image and intent.
2. The technical level of Allegro data sheets must assume a level of technical comprehension and experience on the part of the designer/user…
3. The data sheet should be viewed primarily as an “engineering” document with promotional statements limited to the descriptive front-page text.
4. All abbreviations, terms, symbols, and schematic symbols must conform to national and international standards, which is especially important where the readers’ primary language is not English or where the reader is not an electrical engineer.
5. The data sheet must be grammatically correct.
6. The data sheet should follow a format that makes sense and appeals to the broadest cross-section of readers.
7. The data sheet should provide key fundamental determinants immediately up front – an order of specifications based on importance and convenience to design must be established thereafter.
8a. The data sheet should provide the designer with sufficient and realistic technical and applications information so as to facilitate the product’s design into the suggested application, or
8b. The data sheet should provide sufficient technical information to allow the reader a comparison leading to the replacement of a competitive device.
9. The electrical characteristics of the data sheet serve a dual function of both design information and purchasing information and must agree with Allegro’s internal manufacturing specifications.
10. Applications nuances known by applications engineering, through ongoing customer contact, should be incorporated into data sheets on a continuing basis.
Dewey stops short of specifying how Allegro might measure how well these goals were met.
THE WAY AHEAD
Our industry is extremely conservative. While there’s remarkable innovation in hardware, curiously the industry seems to be quite satisfied with “how it’s always been done” when it comes to software tools and documentation styles that emerged in the 90s. I expect that the companies that will embrace an experiential approach to their technology — rather than focus only on features — will triumph. Here’s what could help them, and us, do better.
— Ditch PDFs in favour of browser-based viewing
In the 90s and 00s PDFs were the only way to create a largely consistent cross-platform viewing and printing experience. But PDFs are bloated, impossible to reliably parse, static, and a possible vector for malware. Oh, and they require the annoying little download-view-delete dance. Their historical advantages are meaningless today. We now have browser-based rich, dynamic, and lean content presentation that’s truly cross-platform. We can achieve a lot more visually and experientially with web content than we possibly could with PDFs (just look at the possibilities enabled by D3 and other data visualisation frameworks). PDFs are the past and rich web content is the present.
Look, for example, at how different the datasheets by Atlas Scientific are. They are not perfect, or even particularly great, but they are fresh and different. We need more of that. Unfortunately, they missed a trick in not making them as webpages instead of PDFs.
— Provide machine-readable information and formulas for figures
In 2013 I suggested that including machine-readable data as part of the datasheet will allow much improved DRC and save money as a result. It will also improve searching and comparison between components from the same, and different, manufacturers. Dewey suggested that well before me.
Every bit of tabulated data should be provided in a text-file data structure. CSV, XML, JSON, YAML; it doesn’t really matter which. There’s no standard for arranging that information yet but maybe one will emerge when this becomes the norm. Currently what we have is the most basic data that’s manually extracted from PDFs or provided by the manufacturer. Therefore, it’s the only data we can search and filter by and that’s not good enough. Imagine being able to filer on the basis of a timing figure that you particularly care about.
Similarly, static, tiny, plots only give a ‘feel’ for characteristics. Every plot should be accompanied by a generation formula together with tested data points so that the user can calculate and view exact data, and be able to compare it in a manner that makes sense to their application.
— Create multiple views
We digest datasheets in two modes:
Search mode:
We are ‘designing-in’ a component. We scan the documentation of many components for specific attributes that are important to us. Ideally we want to spend as little time as possible with a document before we reject a component as unsuitable.
Design mode:
We’ve committed to a component. We now need to make it work perfectly within the context of our design. Ideally we want to find all the data we need, logically organised, in one place, without encountering any surprises about the device’s attributes that were not obvious in search mode.
In a dynamic page we can create multiple optmised viewing modes. In search mode we might have headline figures including calling attention to potential pitfalls (performance requirements and quirks, errata, production status, obsolescence information, etc.) In design mode we’d expect the entire data to be available in an uncluttered, intuitive, linked, and searchable dynamic format.
For those who’ll protest with “give us our datasheets back” it’ll be wise to create a view that emulates the antiquated static look. This view could be available as PDF in order to complete the experience. Half-joking aside, a printable version of the datasheet in any mode is essential.
— Perform user-experience (UX) testing
Through user-experience testing we can learn the deficiencies of a product or its documentation in order to improve both, ideally before it goes to market. Today it’s an essential part of product development. IC and module manufacturers should conduct such tests in order to improve their offerings to reduce frustration and provide a positive experience to their customers.
(We know for certain that manufacturers don’t already do UX testing because many footprint definitions still suck. If they ever listened to our grumbles they’d know that most of us prefer centre-to-centre definitions.)
Effective user-experience testing is deceivingly difficult and should be performed by those who know what they are doing. I think, however, that hiring UX pros might just be too big of an ask from IC manufacturers initially. Any testing would do to start. They should take a handful of potential customers (not employees) with a range of experiences and let them to design a small product with their chip. Interview; learn; improve; repeat. That would already be a huge improvement.
— Manufacturers should also do these
Use revision control
All hardware companies already use version-control software internally, right? Right? They should consider making the documentation bit, or only the releases, to be available through a public host. Just this will help with all of the items below.
Update often
Every delay in correcting, adding, or clarifying data in a datasheet contributes to negative experience by users. There’s no reason to bundle them into major releases. Since webpage datasheets are much easier to update and distribute than PDFs, manufactures should update datasheets as soon changes are required.
Place documents in permanent location in perpetuity
The reason why every component distributor hosts their own — often out of date — instance of documentation is because manufacturers keep moving them around. Searching a part name doesn’t always lead to the manufacturer’s page where, if we’re lucky, the latest version is available. Manufacturers need to define an easy to guess location that will always point to the latest documentation, surviving redesigns. For example:
<manufacturer’s website>/<part number>/datasheetKeep users updated
Manufacturers should allow users to subscribe to component-specific notification where they will get alerts — only alerts! — about that particular component. A message might be sent with every revision, errata, change to production status, and obsolescence notifications. On a webpage datasheet subscription could be a simple form.
Be complete and point out pitfalls
Jason Sachs concludes his article on ‘How to Read Power MOSFET Datasheet’ with the following:
- Minimum and maximum specifications are the only other part of a datasheet that you can rely on. (They’re practical guarantees even if they’re not legal guarantees.)
- Unless otherwise specified, characterization graphs show typical values — you might learn qualitative behavior from them, but you can’t rely on them in a quantitative sense.
Manufacturers should be entirely complete and transparent about the data they provide and shouldn’t be concerned with data that ‘looks bad’; users eventually find out anyway. When manufacturers point out pitfalls users do not react with disgust, but with thanks which builds a longer-lasting relationship. A manufacturer may lose this ‘socket’, but win a long-term future customer.
Do not restrict access to documentation
Manufacturers should not under any circumstances impede access to any documentation by requiring any details or registration in order to view it. I still see this in the wild and it’s infuriating.
WHAT NOW?
Manufacturers need to accept that better, honest, and complete datasheets make for happier customers and lead to more business in the long-term. While their big clients don’t usually suffer from current deficiencies like the rest of us, manufacturers would be wise to treat our time with respect and be rewarded with more business and attention. It is only the manufacturers that can make this work and I encourage them to take steps towards some or all of the issues that I’ve raised here. I’m interested in helping them as part of my Boldport Studio consultancy, so those who’d like to pick up the challenge, let’s do it!
