![STEP 2: CHOOSE A VENDOR
17 | © 2015, Palo Alto Networks. Confidential and Proprietary.
• There will be a direct integration from Adobe FrameMaker to AEM.
• FrameMaker styles will be converted to AEM CSS styles
• Appropriate AEM tags will be added to page properties based on document parameters
• Modification of AEM template “PAN – FEATURES TOUR PAGE” to include:
• Search – Component and Results Page
Build a new Documentation Search component that can be dropped onto a page. The search box will be allowed to span
the width of its containing box
Search via tags –This will work just like the Resources search functionality
[https://www.paloaltonetworks.com/resources.html]
Search results will be on a separate page that will match Resources search results layout. The existing search results
template will be used. [https://www.paloaltonetworks.com/resources.html?q=wildfire]
Search results weighted by content. Users will have the ability to add/change/remove content priority
• PDF
There will be a PDF button which when clicked will allow the user to create a PDF on the fly.
The PDF will include the current topic node and all sub-nodes
• Breadcrumb changes to reflect topic hierarchy](https://image.slidesharecdn.com/build-a-doc-portal-final-160322221445/85/Building-a-Documentation-Portal-17-320.jpg)
Building a Documentation Portal
- 1. BUILDING A DOC PORTAL Laralyn Melvin & Matangi Vaidyanathan
- 2. AGENDA • New Documentation Strategy • Portal Strategy • Content Strategy • Portal Development • Portal Demo • Portal Tomorrow 2 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 4. WHY A NEW DOCUMENTATION STRATEGY? • In FY2012 there were 6,948 calls to support for help configuring the product. • Customers and partners report that they are unable to find the content that they need and, often, if they do find the content, it is for the wrong OS version. • There is a large amount of documentation produced by various groups throughout Palo Alto Networks, but it is difficult to find what exists and harder yet to keep it up-to-date. There is also a lot of duplicate content because employees have no visibility into what already exists. • We do not have all of the content expected of an Enterprise-level company. Page 4 |
- 5. SURVEY OF EXISTING “DOCUMENTATION” • Knowledge Base Articles (Jive) • Live Community discussions (Jive) • “Unofficial” tech notes on Knowledge Point (PDF) • “Official” tech notes in the Documentation Community (PDF) • Product documentation PDFs posed in Documentation Community: • Administrator’s Guides (translated) • Command Line Interface Reference Guide • Hardware Reference Guides (translated) • Context-sensitive help (translated) 5 | ©2012, Palo Alto Networks. Confidential and Proprietary.
- 6. TOP PROBLEMS WE IDENTIFIED Top Problems with Existing Strategy Customers do not know where or what type of document—admin guide, tech note, knowledge point article—to look in to find the content they need. Often the complete information they need to solve a problem or perform a task is stored in multiple locations and documents. Customers are unable to figure out how to configure our products and end up calling support. Content is not easily searchable by product or version. Customers don’t always know what they need to search for and our documentation does not provide the context or navigational mechanisms to help them pick up the “scent” of the information they are looking for. Content can be contributed by any internal user, but isn’t maintained or translated. Customers are not able to find quick answers to the questions they have when trying to perform a task or troubleshoot a problem. Not all users like content in the same format. Users who are used to the “Google” model want to be able to search for content within a web-based system. Other users prefer to be able to take content offline, either as a printed document or a PDF, and read it as a unit. Official documentation for all products was in a single admin guide and only provided information on the fields available on each screen, not on the tasks users need to perform to do their jobs.
- 7. CONCLUSIONS FROM ANALYSIS OF PROBLEMS We had two high-priority problems to solve: Page 7 | Top Problems Solution Accessibility/Findability Create a centralized doc portal with dynamic linking to other content. Content Quality Transition to topic-based content architecture and write, write, write.
- 9. WE SURVEYED DOC PORTAL… Page 9 |
- 10. AFTER DOC PORTAL… Page 10 |
- 11. AFTER DOC PORTAL… Page 11 |
- 12. TOOL EVALUATION • Mindtouch • SDL/Trisoft • Madcap Flare • Jive • Adobe CQ5 • FrameMaker/Webworks 12 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 13. STRATEGY OPTIONS • Option 1: Traditional Web Help—Use an off-the-shelf help authoring tool to create single source documentation in various outputs and host it on a site that is accessible from the support and/or www.paloaltonetworks.com site. • Option 2: Integrated Web Help—Use an off-the-shelf help authoring tool to compile a linked help system that is then integrated into the support site using the Jive API. • Option 3: Company-Wide Content Management and Publishing Solution— Use of a CMS to author and store, all content authored company-wide and publish to various channels. Page 13 |
- 14. SOLUTION COMPARISON Solution Requirements Web Help Jive Help CMS Help Users should not have to look on multiple sites for content. Employees should be able to see what information exists. Customers should have content that helps them understand how to configure our products without calling support. Content must be easily searchable by product or version. Content can be contributed by any internal user. Collaborative review of content (including translated). Content must dynamically link to content in other channels. Content must be searchable from the KnowledgeBase (Jive). Content must be searchable from www.paloaltonetworks.com. We must be able to update in one place, publish in many. We require multiple output formats from single set of source files.
- 15. THE DECISION: ADOBE CQ5 • Company-wide decision to move to Adobe CQ5 to host the corporate web site, including the doc portal. • Marketing to define web site design, look and feel. • We were to “inherit” look and feel, but own development of our solution. • We would be located at www.paloaltonetworks.com/documentation. • Support site (Knowledge Base and Community) to remain in Jive. 15 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 16. STEP 1: DEFINE STATEMENT OF WORK 16 | © 2015, Palo Alto Networks. Confidential and Proprietary. • Content migration: Move existing FM content to CQ5. Native authoring of new content in CQ5? • CSS: Technical documentation must match look-and-feel of corporate site. • Versioning: Users must be able find version-specific content. • Multiple outputs: We need both PDF and HTML content available for our users. • Translation workflows: Translated content required. • Weighted search: We need to have a search function that is prioritizes content found within the sub-domain more highly than content found in other areas of the domain. • Dynamic linking to Support Community: Related KB articles dynamically generated for topic pages. • Site Metrics: We need a way to know how we’re doing. • Blog Integration: We must be able to integrate a technical publications blog.
- 17. STEP 2: CHOOSE A VENDOR 17 | © 2015, Palo Alto Networks. Confidential and Proprietary. • There will be a direct integration from Adobe FrameMaker to AEM. • FrameMaker styles will be converted to AEM CSS styles • Appropriate AEM tags will be added to page properties based on document parameters • Modification of AEM template “PAN – FEATURES TOUR PAGE” to include: • Search – Component and Results Page Build a new Documentation Search component that can be dropped onto a page. The search box will be allowed to span the width of its containing box Search via tags –This will work just like the Resources search functionality [https://www.paloaltonetworks.com/resources.html] Search results will be on a separate page that will match Resources search results layout. The existing search results template will be used. [https://www.paloaltonetworks.com/resources.html?q=wildfire] Search results weighted by content. Users will have the ability to add/change/remove content priority • PDF There will be a PDF button which when clicked will allow the user to create a PDF on the fly. The PDF will include the current topic node and all sub-nodes • Breadcrumb changes to reflect topic hierarchy
- 18. STEP 3: CREATE WIREFRAMES 18 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 19. CONTENT STRATEGY
- 20. DRIVERS FOR CONTENT STRATEGY • Problem statement evaluation dictated a move to task-based content. • CQ5 not ideal for authoring large amounts of content. • Very small team to manage portal development and write all new content. • We needed to deliver LOTS of content while the portal was being developed. • Decision: Continue to write in FrameMaker and develop a custom FrameMaker to CQ5 API that would map our FrameMaker paragraph, character, and table styles to CSS. Page 20 |
- 21. CONTENT VISION • Hybrid content model: Content would flow-like a book, but individual topics would stand alone. • Think of content in categories, not chapters. • Topics defined by head levels (Chapter heads, L1 heads, optional at L2). • Focus on complete workflows instead of discrete tasks. • Facet-driven: We would tag topics to reveal relationships within content authored in a book construct and allow users to narrow to find what they need. • SEO optimized. • Prioritize based on customer need (SalesForce data). Page 21 |
- 23. CUSTOM API • Finalize FM templates so styles could be mapped to CSS. • Customize the API that Adobe provides for integrating FM and CQ5. Exports FM as XML, generates PDF of whole book and PDF “sections” for each chapter of the book and renders HTML in CQ5. • After upload, we must activate the HTML content, images, PDFs in CQ5. Built custom “FrameMaker Manager” tool in CQ to reduce chance of human error. 23 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 24. SEARCH • SOLR-based search functionality built from scratch. • All content immediately indexed upon upload. • Defined facets and corresponding tags. Facets include OS Version, Product Category, Feature Category, Feature, and Information Type. • Tag individual topics after upload (couldn’t get index markers to export). • Our search was cool- Marketing and Support teams leveraged our SOLR implementation. 24 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 25. SITE METRICS • SiteCatalyst for metrics collection • Total number of visits • Top pages • Unique users • PDF downloads • Entry/exit points • Keywords report 25 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 26. CHALLENGES DURING DEVELOPMENT • FrameMaker XML export degrades image quality. • Many FrameMaker elements not exported in XML (i.e. Index markers, named destinations). • FrameMaker source must be perfect for upload to succeed. • Difficult to troubleshoot upload failures. • Difficult to get exported XML to map cleanly to CSS. • URLs not static. • KB Search not included in first phase of project. 26 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 27. PORTAL DEMO
- 28. FOCUS ON FINDABILITY Many paths to the information to facilitate all types of users: • Top-level organization of content allows browsing by product category: • Quick links provide access to different OS versions. • Second-level browsing for broad product categories, such as PAN-OS or Platforms. • Users can search when they know exactly what they’re looking for: • Use quotation marks to find an exact word or phrase. • Synonyms and protected words provide more robust search results. • “Read More” links help you find what you’re looking for more quickly. • Users can narrow results using facets when not exactly sure what to look for: • Facets include OS Version, Product Category, Feature Category, Feature, and Information Type. • Find relationships between features. • Hybrid web-book model allows linear browsing or quick jumps: • Hybrid topic-based/book-based model enables browsing through books. • Inline links allow you to jump to related information quickly. 28 | ©2012, Palo Alto Networks. Confidential and Proprietary.
- 29. BOOK UPLOAD: FROM FRAMEMAKER 29 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 30. BOOK ACTIVATION: FROM ADOBE CQ 30 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 31. 31 | © 2015, Palo Alto Networks. Confidential and Proprietary. LIVE DEMO Palo Alto Networks Technical Documentation portal: https://www.paloaltonetworks.com/documentation
- 32. SITE METRICS 32 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 33. SITE METRICS 33 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 34. SITE METRICS 34 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 35. SITE METRICS: TAKEAWAYS 35 | © 2015, Palo Alto Networks. Confidential and Proprietary. • We have seen a steady increase in traffic to our site as measured in page views (72,882 page views in January 2015 vs. 263,561 page views in January 2016). • 78% of traffic to our site is from Windows systems; Mac OS users 14%; mobile devices only make up 3.7%. • The majority of our users enter the site directly (52%), either from Google (80%) or by entering the URL directly or using a bookmark (20%). Of the users who come from another site within Palo Alto Networks, 23% come from Live. • On average, users spend about seven minutes on our site and click through nine pages.
- 37. INTEGRATED SEARCH 37 | © 2015, Palo Alto Networks. Confidential and Proprietary. • Support community has moved from Jive to Lithium. • Our search results now include content from Lithium. • SOLR indexing Lithium content daily. • Our search results will also include KB articles dynamically.
- 38. 38 | © 2015, Palo Alto Networks. Confidential and Proprietary. INTEGRATED SEARCH RESULTS
- 39. RELATED CONTENT 39 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 40. ABILITY TO SET SEARCH SCOPE 40 | © 2015, Palo Alto Networks. Confidential and Proprietary.
- 41. STRUCTURED FRAMEMAKER 41 | © 2015, Palo Alto Networks. Confidential and Proprietary. • Will produce more robust XML. • No longer will need to strip graphics from PDFs for high-quality images. • Will allow us to use richer graphics/media within our topic pages. • Will reduce cost of translation because we will send XML instead of FM. • Will allow us to upload translated content to our localized sites instead of having translated content in PDF only. • Will reduce time spent troubleshooting upload issues caused by tagging errors.
- 42. COMMENTING AND RATING OF CONTENT 42 | © 2015, Palo Alto Networks. Confidential and Proprietary. • Metrics provide some insight into content, but we still have to guess. • Users will be able to comment on and rate individual topics. • We will have the ability to moderate comments. • Marketing will leverage the solution we develop.
- 43. 43 | © 2015, Palo Alto Networks. Confidential and Proprietary. Q & A
Editor's Notes
- #13: Author IT we did not evaluate
- #19: Transition to a category based content model
- #24: Our developer team customized the API for our needs. We wanted the FM content to be transformed to XML, and viewable as both HTML and PDF. The L0 headings were our left navigation “category” and each L1 or L2New Topic was a standalone HTML page.
- #25: SOLR is an open-source Java search server. Solr is for indexing text. Because our database contains documents with lots of unstructured text (not fields/columns), it speeds up search. SOLR fully indexes all the HTML content (and PDFs) on our sub-domain to make it searchable. It allows you to programmatic retrieve data quickly with the same speed as something on the first page or something off page 900,050. Marketing used the SOLR for searchability in their Resource Center. And Support integrated it with Salesforce so that Support engineers couls have our content at their fingertips.
- #27: We could only use png images.
- #29: content and portal strategy resulted in findability Top-level organization: https://www.paloaltonetworks.com/documentation Second-level browse: https://www.paloaltonetworks.com/documentation/pan-os.html https://www.paloaltonetworks.com/documentation/platforms.html