Tips for effective use of technical documentation

Article By : Parker Dorris and Lauren Handel, Silicon Labs

Design engineers can use these tips for effective usage of hardware, software, and development tool documentation.

You start a project with a clear vision of your design needs, project goals, and a successful, on-schedule launch. Maybe you’re a leading Internet of Things (IoT) product developer creating a new family of wireless sensors. Maybe you’re building a drone for a project outside of work. You have chosen the hardware and software development tools you will use, and you are confident in your ability to learn the rest along the way.

Once you start developing, you get sucked into a black hole of cryptic compiler errors, integrated development environment (IDE)-specific problems, and compliance regulations. First, you scramble to find helpful documentation on the vendor’s website, and then you turn to desperate Google searching.

A developer often encounters documentation-related ‘gotcha’ moments that result in days of lost effort and confusion. Have you ever used information from a seemingly perfect document, only to realize it’s the wrong version, describing deprecated application programming interfaces (APIs)? How about discovering after weeks of development that the product on your evaluation board has been designated NRND (not recommended for new designs)? If this sounds a little too familiar, it’s time to change how you engage with technical documentation.

This article walks through a typical developer workflow from initial evaluation until design completion and beyond. Use these tips for effective usage of hardware, software, and development tool documentation as you need them during your developer journey.

Before development

Choose the vendor based on high-quality documentation, not just fancy hardware. Selecting a vendor can make or break your developer experience, and in most cases, selection begins by choosing the right evaluation board. It can be tempting to simply check the hardware specifications and the expected delivery date of your development board and click “Buy.” This may save you some time at the onset of your project, but you will be kicking yourself later on when you discover that the documentation is disorganized, unreadable, or outdated.

Set yourself up for success at the onset by holding the software and development tool documentation to the same standard as the hardware datasheet. For example, if you find that a vendor offers an MCU with a digital peripheral that can operate in a specific mode that supports your application’s design requirements, do a corresponding check of the vendor’s software API documentation to ensure that configuration and control of that specific mode are well defined. Seek out vendors that offer tutorials and introductions to teach you how the peripheral functions and how to integrate that functionality into your project. Bonus points if the vendor offers reference design material focused on your particular market segment.

Working through “getting started” examples

You might find it daunting to evaluate a vendor’s entire documentation collection before you begin your project. Take a step back to the basics and start with looking at different vendors’ “getting started” guides.

What makes a good getting started guide?

  1. Guides you through tools installation, complete with code examples and compiler setup
  2. Gets hardware up and running with newly-installed tools
  3. Encourages you to make an edit to code, re-compile, and observe a change

Now, what makes a great getting started guide? A great guide accomplishes all of the above goals and leaves you with a clear sense of what comes next. When selecting a vendor, narrow your list to those with great getting started guides. Later on, in development, you can refer to these guides to get your bearings with the tools and technology you are working with.

screenshot of Silicon Labs' simplicity studio software

 

Version history

When choosing a vendor, give preference to those that provide easy access to software documentation for older versions of their stacks and libraries. For instance, as you develop, new versions of the stack will likely release. Whenever a stack version updates, you have to decide to update or stick with the version you have.

If you stick with the version you have, it’s important to know that you still have access to docs relevant to your version of the stack. For PDF sourced docs, you’ll want to check for a revision notes section. Look for vendors that allow you to access older versions all in one online platform. Without an online documentation system or some other bulk doc download method that collects all docs for a specific stack version, responsibility will fall on you to collect and save all the documentation you need.

Sample a doc

The key to improving your documentation experience is choosing high quality, readable, and accurate documentation before you start implementing your solution. Find a document that you know would be useful to you later in your development journey. Read through that document carefully and assess its legibility and organization.

What do the comments on upfront embedded software docs look like? Are they high quality, readable, and written in your native language? Make sure that the document gives you actionable information, such as how to exercise a peripheral for a specific task.

Developer checklist

Developer checklist for success:

  1. Compare and contrast documentation across vendors before purchasing hardware
  2. Work through a couple of getting started examples
  3. Synchronization to stack releases—can you access older versions of the stack documentation?

The need for up-to-date and easily accessible documentation does not stop when development nears completion. You spent the beginning of development taking a concept to a prototype, and the last stages of development will be spent evolving your prototype to a product that is market-ready. After a successful launch, you’ll need to monitor documentation for updates and notices. Choosing a reliable vendor that supports developers throughout those final stages ensures a long-lived product lifecycle.

Certification documentation

Vendor products provide certification documentation to support their customers in target market segments. For instance, developing a product with wireless connectivity means checking that software stack components and module designs have been certified by various standards.

Not all of this documentation will be available on a vendor’s website, as some information will likely be released on a website hosted by the body doing the certification. Look out for vendors that provide certification documentation as well as guidance to any off-site resources.

Product life cycle and software notifications

After launch, you or someone in charge of procurement must be vigilant and monitor for any lifecycle updates to every component in your product. A vendor might release a silicon revision to the MCU you chose, and you’ll have to decide whether to update your own product’s bill of materials (BOM) to the new rev.

Sometimes, if a product reaches end of life (EOL) status, you won’t be given a choice, and a redesign is required. All silicon vendors release product change notifications to notify customers of lifecycle updates, and the top vendors provide customers with the ability to subscribe and receive notifications automatically.

Some vendors provide a similar subscription service for updates to software such as stacks and libraries. For example, you can subscribe to security notifications and quickly update your product’s software accordingly to ensure that your products provide the highest level of security for your customers.

Below is the developer checklist for product lifecycle and software notifications:

  1. Subscribe to product change notices (PCNs)
  2. Seek out vendors that offer software advisory systems

Be the exception

Developers often waste precious development cycles sorting through long lists of documentation or articles on the vendor website instead of focusing on keeping their projects on schedule. You can be the exception. Scope out the best hardware, software, and development tool documentation before you purchase your development boards. Identify the support communities that will give you highly-detailed and relevant answers when you need them.

After design completion, seek out up-to-date qualification documentation for your technology solutions. Your future self will thank you for replacing hours of frustration with moments of clarity during development.

As an example, imagine you are starting a project that requires Bluetooth Low Energy (BLE) connectivity. You evaluate Silicon Labs as one potential vendor, and its EFR32BG22 system-on-chip (SoC) as a solution for your BLE connectivity requirement. From the start, you will notice the vendor provides a training portal with over 40 educational videos on Bluetooth. The online platform includes concise getting started guides for each development tool and organized, cross-linked API documentation.

The software documentation platform provides wireless protocol certification guides, product release notes, and version history for all API documentation. After development, when you want to stay informed on the product lifecycle, you can subscribe to a notification system to stay updated on PCNs and errata.

Parker Dorris is a senior product manager for Xpress devices at Silicon Labs, and Lauren Handel is a product management intern at Silicon Labs.

Related articles:

Leave a comment