Try announcing documentation isn’t important in semiconductor development. You’ll be outed as a heretic! Ask people to write it and you’ll hear a sigh. Ask for an example of decent, truly useful documentation and people struggle to find it. To put it mildly, in semiconductor development we’ve got a love/loveless relationship with documentation. We all agree it’s critical but we don’t like writing it. That and we kind of suck at it anyway.

But we can change that. By putting more thought into who we’re creating documentation for and some friendly reminders around how we create it, we can end up with documentation we’re proud of.

What you create depends on who you’re creating it for…

Documentation for Users

Pretty much everything we build as design and verification engineers, in one way or another, is IP that’s used by at least one other team, probably more. Given that the productivity of those teams hinges on the usability of your IP, the absolute most important type of documentation you create, by a mile, is a user guide.

Unfortunately, we tend toward design documentation and that design documentation doesn’t typically function well as a user guide. We need to specifically write user guides. Always. And user guides we write should be written for users. At a minimum, cover the following in just enough detail-just enough being the careful balance between too little and too much:

• Summary of supported and unsupported features
• Integration
• HW/SW interfaces and protocols
• Reset, setup and initialization
• Intended usage of each feature

Avoid architectural rambling and implementation details unless they are absolutely necessary (Hint: 99/100 times they aren’t). Use examples or code snippets where ever possible. Bonus marks for including and maintaining real, stand-alone examples as part of your user guide. Oftentimes a real example is the only “user guide” people want so supplying that from the outset will make a lot of them very happy.

Documentation for Colleagues

In this context, I’m not talking about users of IP but colleagues that share or at some point will assume responsibility for your IP. In my experience, this is the hardest documentation to write because it requires the most detail. It also involves you guessing at how people will interpret your IP, the questions they’ll ask and the answers they’ll find acceptable.

Personally, I think preemptively documenting your IP in a way that it could be handed off to somebody else, anybody else, is a futile effort. There is no way to prepare for the just-in-case-you-get-hit-by-a-bus scenario so attempting it is a waste of time. You’re much better off just waiting for the bus scenario, then sitting down with the person taking over for you for a couple days with a whiteboard. Explain everything, answer questions in real-time and take breaks to produce whatever documentation they need as you go.

If you’re absolutely stuck preemptively writing documentation for colleagues, stick to summary concepts. Take the user guide as a starting point and supplement it with architectural diagrams, data/control flow diagrams and any other kind of diagram that captures your implementation and intent. Avoid drilling too deep; you’re just as likely to confuse people with overwhelming detail than help them. And overwhelming detail is harder to maintain so it opens the door wider to obsolescence and misinformation.

Documentation for Yourself

I’ve never been a big fan of formal structures and processes for design documentation. It’s always felt to me like they’re geared more toward producing reviewable collateral and checking boxes than they are for supporting good design.

This may grate on a few nerves, but I think it’s more productive to give developers the flexibility of capturing intent that’s useful for them than imposing formal structure. Developers should produce as much or as little as they need to capture their intent and produce their IP. There should also be flexibility in form and format with a requirement that collateral is easily reviewable by other developers.

Some guideline always apply…

Usage Model First

A clean usage model documents itself. That is, as your IP more closely aligns with what people are expecting and using it becomes increasingly obvious, instructional documentation becomes less critical. That’s not to say you avoid the documentation. Just that designing a clean usage model puts you in the enviable position of building more of a reference guide than a true instructional guide. If you find yourself repeatedly insisting people consult your documentation or you find yourself constantly updating your documentation in response to questions from users, consider the possibility your usage model could use a facelift.

Avoid Rat Holes

Documenting necessary features that make sense is hard enough. Documenting obscure, can-also-do features is much harder. If you’re having difficulty documenting a feature, it could be a sign that your usage model needs some work. Or consider the possibility you’ve over-engineered a feature into your product that shouldn’t be there.

You Can’t Document Everything

Speaking of rat holes, the biggest rat hole presents itself with the idea you can and should document everything. You can’t document everything. It’s not possible or even useful. Don’t bother trying. Do a good job of capturing what needs to be captured while keeping your other lines of direct support open. Being present for questions and support for individual users, however annoying you think it might be, is time much better spent than trying to create bullet proof documentation.

Keep It Current

Nothing upsets users more than revising obsolete documentation after they’ve integrated obsolete features. Of course there’s the immediate re-work penalty they’re forced to pay. But there’s also the side effect of burning trust and creating suspicion of future documentation.

The only way to avoid obsolete documentation and the resulting devastation is to treat documentation as a continuous exercise. Update weekly at least, daily is better, real-time as changes happen is best. However you capture your documentation, keep it open, keep it handy, keep it current.

Keep It Accessible

This is an opinion, the right opinion, but an opinion nonetheless: the only useful documentation is web accessible, application agnostic documentation. No downloading, no versioning confusion, no application or viewing restrictions, no email attachments, no indirection, definitely no paper. Basically, nothing that obstructs or obscures users from using your documentation, and that’s only possible with web accessible, application agnostic documentation.

-neil