From Friday, April 19th (11:00 PM CDT) through Saturday, April 20th (2:00 PM CDT), 2024, ni.com will undergo system upgrades that may result in temporary service interruption.
We appreciate your patience as we improve our online experience.
Developer Center Resources
NI Tools Network Developer Center » Creating and Managing Reusable Code » Documentation Best Practices
Another important aspect of reusable code is making sure that other users know how to use it. Documentation is very important for making a quality product. Just like you wouldn't release a product without testing, you shouldn't release a product without good documentation.
Why is Documentation Important?
Users remember early experiences with your product. If they have an issue and can't resolve it with resources that you provide, that’s a bad experience. If, on the other hand, documentation already has the answer, users perceive that the product comes from a professional organization.
Documentation also reduces the amount of support you must devote to calls/e-mails/forum posts etc. All support channels require man-hours to respond and therefore reducing these calls can save money. If a customers question is already answered in documentation, this prevents the customer from needing to contact support.
What Types of Documentation are Important?
Add-on documentation should accomplish two main goals. The first goal is to answer questions users have prior to using the product, unrelated to specific features. The second goal is to provide support for customers as they use specific features in your product.
Pre-Use Education
Your first documentation goal is to guide users from reading about and knowing your product exists to being ready to start using the product. The key to providing this pre-use information is to provide answers your users would otherwise have to test and discover through trial and error.
Consider installation as an example. If you just ship a standard Windows installer and all a new user must do is click a Next button 4 times, they may not need any additional information. However, consider a user who is upgrading from a previous version of your product. If upgrading requires some special step—like that users must uninstall the old version before installing the new one—that’s an example of documentation that should be provided to ensure user's are successful on the first try.
Some things to consider in Pre-Use Documentation:
- What special installation steps are required?
- For an upgrade, what new features/bug fixes are available?
- What OSes/LabVIEW Versions does the product support?
- Where does a user find features, examples, and help to get started?
- How does a user get support?
- How does a user purchase the product?
You can deliver this information to your customer in several formats:
- Quick Installation/Setup Guide - provides the customer with a short guide to product setup, think of the setup guides often shipped with printers and new PCs
Example: https://www.ni.com/docs/en-US/bundle/labview-wireless-sensor-network-module/page/lvwsnhelp/wsn_tutor... - Upgrade Notes - provides customers with a list of features and changes in the latest product release and documents any code changes customers will need to make in order to use the new version of your product
Example: http://www.ni.com/pdf/manuals/371780f.pdf - Product Readme - this document can contain all pre-use education information and is the most common format. Customers are familiar with Readme documents and the information they contain.
Example: https://www.ni.com/pdf/manuals/ni-dcpower-linux-2022-q3.html
Here is a template you can use to create a product readme: Template for Readme Document
In Product Support - Context Help
After the readme document guides your users from installing your product to starting to learn how to use it, the next step is to provide resources a user can turn to when they hit obstacles while using your product. The first obstacle for a user is often knowing whether or not a particular VI or feature is appropriate for the goal they want to accomplish. A good Context Help description is vital to educating users about which VI they need to meet their use case.
To write context help, you need to create a VI Description for a VI. This can be done in the VI Properties window for a VI. You write VI descriptions on a per-VI basis. However, there are tools that you can use to make batch-documentation for multiple VIs easy. See here for more details.
A good VI description is one that supplements the VI name. Users generally know what results they want (e.g. they want obstacle data from the sensor) and they know what data they have available as an input (e.g. they know they have a connection to a distance finder sensor), so a description that encompasses that information allows users to quickly identify that this is the VI they need when they hover over it in LabVIEW.
For example, a good description of the above VI might be "Returns two arrays that describe the magnitudes and angles of obstacles the device detects within a given range.” This describes the Action which is taking place, the Inputs that the VI expects and the Outputs that the VI returns.
Some other information that is useful in Context Help are good input/output descriptions, default values for optional inputs, error codes the VI might potentially return, and units in which a VI understands.
In Product Support - Detailed Help
The Context Help should only contain a small bit of information to give a general understanding of how the VI works. If there is more information that will be useful, you should includ this in the Detailed Help. This can include information such as a step-by-step instructions on how to use the VI, details of algorithms the VI uses, examples of how to use the VI, etc.
The detailed help for a product can be any type of document, however if you want to include a link to it from the context help, LabVIEW supports .chm and .hlp files. Having detailed documentation directly accessible from the block diagram can make it tremendously easier for a user to find it. There are many tools available for creating these document types, one of which can be found here. Also, you can create a VI that will load PDF, HTML files, etc from the Help menu.
Additional Resources
- Template for Readme Document
- VI Properties Editor
- VI to XML Documentation Tool (For creating CHM Compiled help documents)
- NIWeek Session: Professionalize Your Add-On or App With Icons and Documentation Best Practices
Third-Party Tools
Check out the following third-party tools for creating documentation for LabVIEW APIs and applications:
Next: VI Package Manager
Return to: Creating and Managing Reusable Code
