ni.com - SDL.com

ni.com
Putting It All Together:
Using DITA to Create Interactive Help
Kyle Schwamkrug
ni.com
Our Mission
We equip engineers and scientists with systems that
accelerate productivity, innovation, and discovery.
ni.com
3
Our Customers
Advanced Manufacturing
Wireless
ni.com
Aerospace and Defense
Consumer Electronics
Energy
Transportation
4
What We Do
We provide graphical software with modular hardware to build
measurement and control systems.
Low-Cost Modular Measurement
and Control Hardware
ni.com
Productive Software
Development Tools
5
Highly Integrated
Systems Platforms
Scattered Documentation Silos
ni.com
6
Attempts to Alleviate the Problem
Content on ni.com
In-Product Search
User feedback still
indicates documentation:
• Is difficult to find.
• Does not help teach
users how to use NI
products.
ni.com
7
Out-of-Date Processes
The Good
• Source control
• Early XML adoption
• Single sourcing
• Automation
•
•
•
The Bad
• Multiple toolchains
•
•
•
•
Publishing
Testing
Localization
•
•
Bad practices
•
•
ni.com
8
Unstructured Framemaker
Hand-written HTML
Home-grown XML Schemas
Access databases
Documentation in source code
HTML munging
Lack of Unicode support
Vision for the Future
•
•
•
Use NI software applications to channel users to content.
Interactive help—Don’t just give users lists of instructions.
Leverage the power of the Web.
•
•
•
Break down content silos.
Utilize modern standards.
Unified content creation process.
•
•
ni.com
Large-scale content reuse.
Automated publishing to multiple formats.
9
Demo
ni.com
10
How Did We Do It?
ni.com
11
Solution Diagram
Web Browser Control
.NET Web Hosting APIs
HTML
Open Toolkit
ni.com
12
HTML
CSS
JavaScript
Images
Guided Help
XML
•
Simple format—Anticipate users creating their own Guided Help.
•
XML manifest file
•
•
HTML
•
Content—HTML/Images/CSS
•
HTML
•
•
•
HTML
ni.com
Quizzes: DITA 1.2 Learning and Training Interactions Domain
Software interactivity
•
HTML
Page sizes
Page ordering
JavaScript API—Ultimately calls a service provided by web hosting API.
Button styling in CSS
DITA specialization
<div class="trigger opendocument"
onClick="nightrigger.OpenDocument('Answer.gvi', 'Diagram')">
<div class="trigger-text">
<p>Open</p>
<p>Answer.gvi</p>
</div>
</div>
13
Context-Sensitive Help
<member id="InverseCosine">
<helplink>
nihelp://labview-mydaq/inverse-cosine
</helplink>
<infotip>Computes the arccosine of
a specified value (x), where x is
in radians.</infotip>
<contexthelp>
<p>Computes the arccosine of a
specified value (<b>x</b>),
where <b>x</b> is in radians.</p>
<p>If <b>x</b> is not complex and is
less than -1 or greater than 1, the
result is not a number
(<span class="mono">NaN</span>).</p>
</contexthelp>
</member>
ni.com
•
•
All UI elements that should have
help have a help identifier.
Some elements use composite help
IDs to facilitate reuse.
•
•
•
•
GenerateSineWave.frequency
GenerateSquareWave.frequency
<infotip>—Brief, plain text
description.
<contexthelp>—HTML content,
including images and MathML.
14
LabVIEW API Reference Specialization
<nodeCollection>
•
LabVIEW is our programming language; existing API
reference solutions insufficient
•
<vi> topics nested under <nodeCollection> topics in
the map.
<vi>
•
•
<lvParam />
<lvParam />
<vi>
•
Parameters (<lvParam>) are discrete topics, nested
inside of <vi> topics.
•
•
<lvParam />
Listing of nodes is output of standard DITA child links!
Icon filenames derived from help identifiers.
Conref <lvParam> to reuse parameters.
Parameter and VI help identifiers available at output
time for building composite help identifiers.
<lvParam />
ni.com
15
Additional System Customization
ni.com
16
Copy as Conref Macro
•
•
•
•
Conref wizard is inefficient in some cases
XMetaL macro copies a content reference to the clipboard.
Rules checking (i.e., does the element have an id attribute).
Supports single elements and ranges of elements.
ni.com
17
Content Validation Plugin
•
•
•
At check-in, validates content against rules beyond DTDs.
Write plugin (formerly OnDocStore)
Currently checking content against around 75 rules.
•
•
ni.com
Plain-text Infotip content
SVG fonts
•
•
18
URL standards
Require <section> elements
to include <title>
Localization
•
Unique localization process and organization.
•
•
•
•
•
Translators are NI employees.
Significant process automation.
Simultaneous product releases.
Translation process involves translators pulling content on-demand.
Out-of-the-box LiveContent Architect translation process requires
writers to complete content before it can be translated.
ni.com
19
Solution—Custom Localization Process
•
•
Custom metadata tracks which files have up-to-date translations.
Application uses the LiveContent Architect web services API to import
and export files.
ni.com
20
Lessons Learned
ni.com
21
DITA is Not Business as Usual
Organization-wide understanding of the ramifications of structured
authoring is necessary.
• Authoring and formatting are separate tasks.
•
•
•
Writers and subject matter experts will have trouble letting go.
Adopting a standard can help push back against feature creep…
But, it can also be a target of frustration.
ni.com
22
Develop a Reuse Strategy
•
Very skilled writers will sometimes feel an urge to over-reuse.
•
•
•
•
Easy for topics to become “write-only.”
Impact of changing a topic becomes difficult to analyze and manage.
Translation might be impossible.
Carefully analyze product similarities and volatility.
•
•
ni.com
Look for broad similarities.
Focus on volatile information.
23
Involve Product Development Teams Early
•
•
•
Their challenges are likely completely different from content
management challenges.
Ensure they understand your information architecture and motivations
behind it.
Easy to underestimate the impact of a change on content management
processes.
ni.com
24
Keep Your Eye on the Prize!
•
There will be challenges and frustrations along the way.
•
•
•
•
Schedules will change.
Requirements will change.
People will change.
When everything comes together, it’s thrilling!
ni.com
25
Questions?
ni.com
26
ni.com