1

2

Professionalize Your Add-on or App with Icons and

Documentation Best Practices

Robert Des Rosier, LabVIEW Partner ProgramLaura Hayden, R&D Graphic Designer

Steven Moser, Technical WriterNational Instruments

3

Professionalize Your Add-on or App with Icons

Laura HaydenGraphic Designer

4

What I Do

Consistency Reviewer

Image Translator

Icon Artist

5

What "Professionalize" Means

• Brand Your API

• Think About Functionality

• Remove Text

• Don't Reinvent The Wheel

• Use Color Wisely

• Be Consistent

6

Brand Your API

7

Brand Your API

8

Think About Functionality

9

Remove Text

10

Don’t Reinvent The Wheel

11

Don’t Reinvent The Wheel

12

Use Color Wisely

vischeck.com

13

Be Consistent

verb

object

Add Network Device

14

Be Consistent

Get Disk Image

15

Be Consistent

Clear Image Database

16

Putting It All Together

17

Putting It All Together

18

Putting It All Together

19

Tools / ResourcesLabVIEW Icon editor

Axialis Icon Workshop

Corel Paint Shop Pro

ni.com/iconlibrary

LabVIEWPartnerProgram@ni.com

eTrainings at ni.com/addondevcenter

20

Summary

• Brand Your API

• Think About Functionality

• Remove Text

• Don't Reinvent The Wheel

• Use Color Wisely

• Be Consistent

21

Professionalize Your Add-on with Documentation Best Practices

Steven MoserTechnical Writer

National Instruments

22

Who Am I?• Technical writer = writing + testing + usability

LabVIEW Development System Robotics Module MathScript RT Module Control Design & Simulation Module Jitter Analysis Toolkit Third Party Licensing & Activation Toolkit VI Analyzer Toolkit

23

Why Is Documentation Important?

24

Why Is Documentation Important?• Documentation is a product feature

Supplements the software Adds credibility to your products

• Reduces number of support calls• Meets Compatible with LabVIEW requirements

25

Compatible with LabVIEW GuidanceMinimum Recommended

Installing/upgrading X X

Activating X X

Software/hardware/system requirements X X

Getting started guidance X X

Getting support X

Purchasing X

Context Help for VIs/inputs/outputs X

Detailed help topics X

26

What Kind of Documentation is Important?

Goal: Answer “pre-use” questions

Research product

Install/upgrade

Getting started Use features

Goal: Provide in-product support for features

Useractivities

27

Pre-Use Education• How do I install?• If I upgrade, what new features/bug fixes are available?• What OSes are supported? Which LabVIEW versions?• Where do I find features, examples, and help so I can get

started?• If I need support, how do I get it?• How do I purchase your product?

28

Pre-Use EducationSolution: Readme files• Accessible prior to installation• Template available at ni.com/addondevcenter

29

In-Product Support—Context HelpAnswer for users,“Does this fit my use case?”

30

31

In-Product Support—Context Help

VI descriptions

NOT “Acquires data.”

32

In-Product Support—Context Help

“Returns two arrays that describe the magnitudes and angles of obstacles the device detects within a given range.”

33

In-Product Support—Context Help

“Returns two arrays that describe the magnitudes and angles of obstacles the device detects within a given range.”

Verb Output(s) Input(s)”

34

In-Product Support—Context Help

“Returns two arrays that describe the magnitudes and angles of obstacles the device detects within a given range.”

Verb Output(s) Input(s)”

35

In-Product Support—Context Help

“Returns two arrays that describe the magnitudes and angles of obstacles the device detects within a given range.”

Verb Output(s) Input(s)”

36

In-Product Support—Context HelpVI descriptions

NOT “Forward kinematics of a robot arm is computed by this Forward Kinematics VI.”

37

In-Product Support—Context Help

“Calculates the homogenous transform or transforms that represents the position of a robotic arm end effector given the joint angles of the arm.”

38

In-Product Support—Context Help

“Calculates the homogenous transform or transforms that represents the position of a robotic arm end effector given the joint angles of the arm.”

Verb Output(s) Input(s)

39

In-Product Support—Context Help

“Calculates the homogenous transform or transforms that represents the position of a robotic arm end effector given the joint angles of the arm.”

“Verb Output(s) Input(s)”

40

In-Product Support—Context Help

“Calculates the homogenous transform or transforms that represents the position of a robotic arm end effector given the joint angles of the arm.”

“Verb Output(s) Input(s)”

41

42

In-Product Support—Context HelpInput/output descriptions• Provide information users otherwise must test:

NOT “path is the path to the log file.”

INSTEAD “path specifies an absolute path to the file to which you want to log data. If you specify an empty or relative path, this function returns an error.

43

In-Product Support—Context HelpInput/output descriptions• Provide units in which values are expressed,

default values, error information NOT “timeout is the time to wait for a response.”

INSTEAD “timeout (ms) sets the amount of time to wait for a response from the host. If timeout (ms) elapses, this VI returns error code 5. If you set timeout (ms) to -1 (default), this VI waits indefinitely.

44

In-Product Support—Detailed HelpExpand from “Does this fit my use case?”

to “How does this object work?”

45

In-Product Support—Detailed Help• Cross references to relevant examples• Error codes VIs can return• Screenshots of workflows

46

In-Product Support

Solution: Context help + HTML Help• Use tools from Partner team to populate

context help and generate detailed HTML help ni.com/addondevcenter

47

Localization

• English ?• ? English• Vendors and tools exist worldwide, but…• Take advantage of each others’ knowledge—Ask

about solutions at ni.com/addondevcenter

48

Summary

Deliverable: Readme file

Research product

Install/upgrade

Getting started Use features

Deliverables: Context help and HTML help

Useractivities

49

Where to Go from Here• ni.com/addondevcenter

Readme HTML file template VI Properties Editor tool VI to XML tool for creating HTML Help

• Notepad++, KompoZer—HTML editors (free)• FAR—Compiled HTML Help (CHM) editor (purchase)

http://helpware.net/FAR/ Requires Microsoft HTML Help Workshop (free)

50

Related Sessions

Hands-On: VI Package ManagerTuesday 10:30 AM 18C

Creating a Software Evaluation in 10 MinutesWednesday 2:15 PM 10C

LabVIEW Add-on of the YearWednesday 3:30 PM 10C

51

Alliance Partner Network 20th Anniversary Celebration

Join us for an evening of drinks, music, networking, and a celebratory toast by Dr. James Truchard at

5:30 p.m. in the exhibition hall.