Struggling to keep your documentation updated? Looking for a way to ensure a unified look and style of your datasheet?


Author: Vincent Thibaut, Chief Strategy Officer @ Magillem ● Email: thibaut@magillem.com ● LinkedIn: click here


Save time by reusing your IP-XACT design content and streamlining your documentation production with MCP.

Delivering an IP, SOC (FPGA or ASIC), Board or System, isn’t only about delivering the final product, whether it’s virtual -like RTL, Virtual Models, Software…- or a physical device. The associated documentation has always been a crucial part of this delivery. As the product complexity increases, so does the importance of the associated documentation.

Unfortunately, this documentation usually faces two major issues: out-of-date information and inconsistency between datasheet look and feel.
We all know the look on the face of this engineer navigating through hundreds of pages of documentation to find why the behavior of the system doesn’t match his expectation. “Did I find the proper information? Why is it not located where I expect to find it? Is the documentation wrong? Did I miss a configuration somewhere?”. So many hours spent, so many frustrations. “Why? But why?”

Why, indeed, are we struggling to find what we’re looking for? Why can’t we be sure the information we find is accurate? So many doubts.

It shouldn’t be that way. Not with today’s software and automation capabilities. The bulk of the problem lies in how we produce documentation: it is mostly a manual process.

Why is information not correct in the datasheet?


Engineers need to recapture information they have in their design environment in a new documentation format. This explains two main reasons of inconsistency:

    1- When capturing information multiple times in multiple locations, it’s very easy to make a mistake. In our case, the risk is quite important, due to the number of duplicated information.
    2- When you have multiple sources for the same information it’s extremely difficult to maintain the coherency, and often a change made in the design is just not reflected in the datasheet.

Why are datasheets of the same company not always following the same template?


Having to navigate multiple datasheet quickly becomes a nightmare if those datasheets don’t share a minimum of common structure. It’s probably a far-fetched dream to expect all datasheets to look the same, however, even inside the same company, the same product line, and sometimes even between two versions of the same product, datasheet structure is different.

Documentation teams around the word try to solve this issue by issuing guidelines, reference templates, … And they are doing a great job. However, the same problem keeps occurring. Why?

As someone who’s now writing a lot of documentation, I find myself quite obviously falling in the same pitfall as everybody else. A guideline or reference is nice but:
      1- Nothing forces or informs me when I deviate from those.
      2- I need to make a very conscious effort to go and check those guidelines
And, let’s be honest: if I am pressured by time, I often don’t do it.
And there’s also the issue of the template evolution. You don’t want to process all your existing document manually, do you?

Is there a solution?


Yes, there is. I’ll now present it.
It starts with leveraging software capabilities and especially automation. You’ll see this can actually help us address both issues.

Regarding the issue of information correctness:


The first critical step is to identify or create a descriptive metadata format for our design data. Those descriptive metadata will allow our computers to understand two critical information about our design data, structure and semantics.

The second step is to identify or create a software solution which can leverage this metadata format. This must allow us to create, visualize, edit this format, and integrate it with our design environment. Integration is mostly about being able to read and write a strategic subset of design data. This way your descriptive metadata will provide an accurate description of your actual design data.

Ideally this software solution should provide a customer API. A good API allows a more flexible and detailed integration.

To create documentation for semiconductor components (IP, SoCs), a datasheet is the most obvious but not the only existing type of documentation. In this context, the best available design metadata format for such documentation is IP-XACT (IEEE-1685).

I won’t go here in the details of this format; it has its pros and cons, strengths and weaknesses like any format. But the simple fact that it’s an undisputed and widely adopted standard worldwide makes it the perfect candidate.

To solve this issue, two possible solutions come to mind: either an IP-XACT design environment which can generate documentation, or a documentation environment which can import IP-XACT.
The first option could be good enough if we don’t need to add any content to the information coming out of IP-XACT. Since this is rarely the case and since we want to address the template issue for all content, I would recommend the second option.

Regarding the document look and style issue:


Here, the first step, obviously, is to define one or multiple company templates we want to use for the various published documents.

The main step, however, in this case is mostly about the software solution. We can use various publication standards like DITA for example to facilitate the process but even with them a good software solution is the key. This solution must provide a set of critical features:
  • Capability to integrate content into a predefined template.
  • Control rules embedded into the solution to guide user on the proper template usage.
  • Capability to update the template on previously publish document.

  • Using a software solution to automate the translation of your content from one format to another not only avoids inconsistencies, but it also saves a lot of time for the original document creation. This solution can also guide the user to integrate content in a controlled template, thus ensuring a unified look and feel with minimal effort.
    This guarantees your customer an accurate and easy-to-read document while saving your teams time and hassle. It’s a clear win-win situation.
    READ MORE:
    ABOUT IP-XACT (IEEE 1685)
    READ MORE: IP-XACT AS A WAY TO ORCHESTRATE YOUR HW DESIGN FLOW MAGILLEM CONTENT PUBLISHER OASIS DITA STANDARD – Darwin Information Typing Architecture

    Going Further


    We’ve looked at the initial datasheet creation for a single element, but there’s obviously more to it in the bigger picture. As your design data evolves, a deliverable is often composed of multiple elements with a dedicated configuration. You may need or want to trace the actual evolution of your content and generate reports.
    All those things and more should be provided by a global publication document, the datasheet generation being an essential but small part of this process.
    I won’t go into those considerations here, but know that some of the tools mentioned above provide those capabilities and integrate your datasheet generation process in a larger picture solution.