professionalize your add-on or app with icons and documentation best practices
DESCRIPTION
Professionalize Your Add-on or App with Icons and Documentation Best Practices. Robert Des Rosier, LabVIEW Partner Program Laura Hayden, R&D Graphic Designer Steven Moser, Technical Writer National Instruments. Professionalize Your Add-on or App with Icons . Laura Hayden Graphic Designer. - PowerPoint PPT PresentationTRANSCRIPT
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
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.