ni.com - SDL.com
Transcription
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