ditching the desktop: one vendor's leap to hosted documentation
DESCRIPTION
Software vendors increasingly provide their products as hosted services, accessible via online APIs and clients. The timeframe for marketing new features and functionality is often short; tight-knit agile teams write, test, and deploy updates within single short sprints. Documentation must keep up. Enter hosted content providers. Content management and hosting services can fully eliminate the need for onsite writing and publishing tools and infrastructure, allowing writers to focus their energy on developing content. Rich, interactive content is easier than ever to achieve, without requiring writers to leave the comfort of their browsers. In this talk, Tanner Volz describes the exciting process of transforming file-based, linear documentation at iovation (a SaaS vendor), to an agile authoring and delivery process using MindTouch, a feature-rich hosted help and support platform.TRANSCRIPT
@Speaker #LavaCon
Ditching the DesktopOne Vendor ’s Leap to Hosted Documentat ion
Tanner VolzTechnical Content Manager, iovation
Prologue
3© COPYRIGHT • IOVATION 3© COPYRIGHT • IOVATION
BIOGRAPHICAL BLURB FOR UPCOMING COLLECTION OF DOG PORTRAITS
• Portlander who likes the usual things: bikes, beer, film, sleeping
• Music, photo, and video producer on weekends (and at work when I can get away with it)
• Ellie
4© COPYRIGHT • IOVATION 4© COPYRIGHT • IOVATION
BIOGRAPHICAL BLURB FOR PROFESSIONAL CONFERENCES
• Titles: ‒ Technical Writer‒ Information Architect‒ Documentation / Content strategist
• Have helped design and implement enterprise content systems for on-premise and SaaS software offerings
• Many of the usual tools: Framemaker, Robohelp, WebWorks, MadCap, XML / DITA
• Demos, training videos and animations, but I’m not going to talk about that
5© COPYRIGHT • IOVATION 5© COPYRIGHT • IOVATION
ABOUT IOVATION
• Online fraud detection and protection
• Portland-based, ~100 employees
• Real-time SaaS service that integrates with websites, mobile apps, and desktop programs
• Most services available online, including:‒ Browser based admin client‒ User documentation and support‒ Social community for subscribers
6© COPYRIGHT • IOVATION 6© COPYRIGHT • IOVATION
PROLOGUE EPILOGUE
• This has been a wonderful year of creative work, solving a problem that many growing companies face at some point; iovation hired me because I would have fun solving it
• That said, lets start our story in summer 2013…
Act 1Our Story Begins
8© COPYRIGHT • IOVATION 8© COPYRIGHT • IOVATION
ISSUE #1: AUTHORING AND CONTENT MANAGEMENT
• Files from different tools and different authors• Inconsistent semantics and structure• Inconsistent templates• No conditions, variants, or targeting different content to different
users• Shared content copied and pasted; lot of redundancy across docs• Inconsistent versioning and source management• Collaboration by emailing a lot
9© COPYRIGHT • IOVATION 9© COPYRIGHT • IOVATION
ISSUE #2: USER EXPERIENCE
• PDFs, PDFs, PDFs• PDFs aren’t
websites, and aren’t meant to be; Limited cross-document navigation / search
• Repetitive content
• No tracking of customer usage or mechanism for feedback
10© COPYRIGHT • IOVATION 10© COPYRIGHT • IOVATION
ISSUE #3: MAINTENANCE AND DEPLOYMENT
1. Open a Word document.2. Tweak the template.3. Edit some text.4. Copy that text.5. Open another Word document and paste that text into it.6. Attempt and fail to import template changes from first document to the second document. Give up and
manually update the template.7. Update tables of content and save to PDF.8. Optimize the PDFs in Acrobat and verify that document metadata came over correctly.9. Discover that you messed up the content that you edited and copied and pasted and repeat all of the above.10. You never learned how to auto-generate dates and you discover that you forgot to update the copyright date in
a footer. Back to step 1.11. Oops, there’s been a branding change. Back to step 1.12. Open documents in InDesign.13. Make the branding changes.14. Attempt to paste the content changes in InDesign. Realize that pasting across tools decidedly does not work.
Paste the content as plain text.15. Reformat the text you pasted. 16. Fix the pagination that you broke in InDesign when pasting in new content.17. Export the documents to PDF.18. Check in the PDFs to Git to the correct location to make sure that the build picks them up.19. Verify that the PDFs are in the build. QA notices an old PDF that you forgot to update.20. Do all of the above again.21. Ask your build engineer to rebuild. Order gift card.22. Test the new build.
23.Beer.
11© COPYRIGHT • IOVATION 11© COPYRIGHT • IOVATION
Act 2The Hero’s Journey(the 3 act metaphor is a little strained at this point)
13© COPYRIGHT • IOVATION 13© COPYRIGHT • IOVATION
• Cross-platform authoring tools, ideally web-based
• Structured content and semantic tagging
• WYSIWYG + Source authoring support
• Portable content
• Automated builds and deployment
• Easy reuse of common content
• Content and version management
• Search optimization
• User activity and feedback
• 100% customizable presentation using core Web technologies such as CSS and JS
• Lightweight implementation with little or no local installation and system administration
WHAT I LOOKED FOR
14© COPYRIGHT • IOVATION 14© COPYRIGHT • IOVATION
15© COPYRIGHT • IOVATION 15© COPYRIGHT • IOVATION
• Yeas:‒ Great past experiences with many of the most popular tools‒ Very mature solutions, rich feature sets that effectively
support complex needs ‒ Support for essentially limitless output formats and delivery
models• Nays:
‒ Primarily “fat” clients for Windows; iovation is a heterogeneous shop with strong bias toward hosted solutions
‒ Sometimes very heavy proprietary source formats; we need portable, web-ready source
‒ Learning curve for contributors from other disciplines is prohibitive
I LOOKED AT TRADITIONAL DESKTOP PUBLISHING AND ONLINE HELP TOOLS…
16© COPYRIGHT • IOVATION 16© COPYRIGHT • IOVATION
• Yeas:‒ Powerful modular content organization‒ Advanced support for complex content management scenarios,
including reuse, variables, and conditions‒ Localization support in a well-architected system is un-paralleled ‒ XML is very portable
• Nays:‒ Needs do not justify cost‒ This is changing quickly, but effective XML content management
traditionally requires a robust on-premises back-end repository; cost and effort are prohibitive
‒ Transformation to web and print-ready deliverables is still a complex technical challenge, although this is also improving very quickly
‒ Basic HTML markup is already challenging; can’t expect casual contributors to learn a new syntax as well
ON-PREMISES DITA / XML …
17© COPYRIGHT • IOVATION 17© COPYRIGHT • IOVATION
• Yeas: ‒ Editing in place in a browser! Yes, we want this ‒ Just enough word processing to present content effectively
without making authoring too complex‒ Template-driven styling
• Nays:‒ Wikis aren’t CMSes; Some integrate to content management
systems, but this gets very complicated very quickly‒ Typically very rigid presentation options‒ Use wiki or proprietary markup for source (although most
wikis support HTML as well)‒ Single-source publishing to usable offline formats (such as
PDFs) is generally not an option
AND WIKIS
18© COPYRIGHT • IOVATION 18© COPYRIGHT • IOVATION
ENTER HOSTED DOCUMENTATION SERVICES!
19© COPYRIGHT • IOVATION 19© COPYRIGHT • IOVATION
• Rapidly emerging market of CMS providers targeting technical documentation, training, and support sites
• Varying degrees of true SaaS delivery:‒ Some rich browser clients‒ Some requiring virtual machines and local clients
• None are 100% self-contained solutions – always need specialized tools for coding, graphics, video, etc.
• Content management varies‒ Some provide in-place editing with no content management
features, essentially very basic blog platforms‒ Many wiki-style platforms‒ Many social / community platforms for businesses, oriented
towards customer engagement and discussion‒ There are even full implementations of DITA and other XML
syntaxes with UI built around semantic content hierarchies
WHAT IS HOSTED DOCUMENTATION?
20© COPYRIGHT • IOVATION 20© COPYRIGHT • IOVATION
• Output options also vary widely:‒ In-place text posts with basic formatting markup
and no separation of source and output‒ Traditional online help presentation with navigation,
search, index panes‒ Complex multi-level navigation schemes with
customizable search and tagging‒ PDF output ranging from simple linear publishing of
single topics to complex “books” with tables of content
• Bottom line: Increasingly complex market, with different features for different needs
WHAT IS HOSTED DOCUMENTATION? (CONT’D)
21© COPYRIGHT • IOVATION 21© COPYRIGHT • IOVATION
• Met requirements, in particular:‒ 100% web-based administration and authoring‒ Good content management with versioning, content
reuse, variable content management, collaboration, and “single-source” publishing
• Hosted CMS for doc / support is all they do; strong commitment to their market
• Deep roots in Wiki and CMS technology
• Exceptional Sales and Support staff
WE CHOSE MINDTOUCH; HERE’S WHY
Act 3Implementation and Walkthrough
23© COPYRIGHT • IOVATION 23© COPYRIGHT • IOVATION
• Profiling target audiences and building out detailed content plan
• Moving from a pile of linear documents to modular organization
‒ Structuring to serve both "on-demand" modular and linear reading experiences
‒ Identifying and reconciling overlapping content ‒ Deep editorial pass to adhere content to writing standards‒ Fresh technical review of stale content‒ Reviewing and stabilizing branding and terminology
• Formatting topics‒ CSS styles attached to standard HTML ‒ Special classes for styles tied to semantic tags, formatting
overrides
IMPLEMENTATION
24© COPYRIGHT • IOVATION 24© COPYRIGHT • IOVATION
• Formatting PDFs‒ MindTouch uses Prince PDF, an excellent PDF publishing tool
that takes HTML and CSS and its input‒ CSS for PDF-specific content formats as well as elements for
traditional book layouts, such as headers, footers, title pages
• Formatting navigation and page layout‒ Tables of content‒ Breadcrumbs and navigation trees‒ Sidebar‒ Search fields and results lists
IMPLEMENTATION (CONT’D)
25© COPYRIGHT • IOVATION 25© COPYRIGHT • IOVATION
• Styling conditional text and variables• Enabling users to download SDKs
‒ Setting up forms: Enter company details so we can track downloads
‒ Requiring EULA acceptance‒ Generating email notifications to iovation
staff
IMPLEMENTATION (CONT’D)
26© COPYRIGHT • IOVATION 26© COPYRIGHT • IOVATION
WALKTHROUGH
27© COPYRIGHT • IOVATION 27© COPYRIGHT • IOVATION
USER EXPERIENCE: SECURE ACCESS VIA SINGLE SIGN-ON AND CONTEXTUAL LINKS
Log-in to iovation browser client required to display MindTouch site
Contextual links then open
MindTouch site
28© COPYRIGHT • IOVATION 28© COPYRIGHT • IOVATION
USER EXPERIENCE: HIERARCHICAL NAVIGATION AND BREADCRUMBS
Authors define
organization; MindTouch
auto-generates
all navigation
29© COPYRIGHT • IOVATION 29© COPYRIGHT • IOVATION
USER EXPERIENCE: RELATED TOPICS, META-TAGS
30© COPYRIGHT • IOVATION 30© COPYRIGHT • IOVATION
USER EXPERIENCE: SEARCH
Users can filter and sort
results, as well as enter
advanced search criteria
31© COPYRIGHT • IOVATION 31© COPYRIGHT • IOVATION
USER EXPERIENCE: CUSTOM PDF BUILDER
Click a button…
Choose content…
Get a fully formatted
manual with headers, footers,
cover pages…
32© COPYRIGHT • IOVATION 32© COPYRIGHT • IOVATION
USER EXPERIENCE: CUSTOM PDF BUILDER (CONT’D)
Tables of content…
33© COPYRIGHT • IOVATION 33© COPYRIGHT • IOVATION
USER EXPERIENCE: CUSTOM PDF BUILDER (CONT’D)
And PDF-specific
formatting, all
generated automaticall
y from the HTML
source using custom CSS
34© COPYRIGHT • IOVATION 34© COPYRIGHT • IOVATION
USER EXPERIENCE: CONTENT FEEDBACK
Users can rate pages…
And send feedback; we
are notified via email
35© COPYRIGHT • IOVATION 35© COPYRIGHT • IOVATION
USER EXPERIENCE: DOWNLOAD SOFTWARE
Users complete a
form and accept a
license agreement to request
software downloads;
we are notified via
36© COPYRIGHT • IOVATION 36© COPYRIGHT • IOVATION
AUTHORING AND ADMIN: WRITING, EDITING CONTENT
Full featured WYSIWYG editor with customizable toolbar and styles
Source editor for those of us who prefer it; HTML is absolutely
spotless, ensuring 100% portability
37© COPYRIGHT • IOVATION 37© COPYRIGHT • IOVATION
AUTHORING AND ADMIN: “CHUNKING” AND REUSING CONTENT
Store shared content in standalone topics…
And insert anywhere using
simple include statements
This is useful for managing variables as well, such as branding terms
38© COPYRIGHT • IOVATION 38© COPYRIGHT • IOVATION
AUTHORING AND ADMIN: CONDITIONAL TEXT FOR DIFFERENT USERS AND SCENARIOS
Define custom CSS classes to show / hide content for different outputs, different types of users, different stages of readiness
Customize the WYSIWYG toolbar to easily wrap conditions around text
39© COPYRIGHT • IOVATION 39© COPYRIGHT • IOVATION
AUTHORING AND ADMIN: TRACKING CHANGES AND VERSIONS
Detailed revision history
Robust comparison and reversion
40© COPYRIGHT • IOVATION 40© COPYRIGHT • IOVATION
AUTHORING AND ADMIN: MANAGING ACCESS AND USERS
Target any content to any user, either individual or in groups
41© COPYRIGHT • IOVATION 41© COPYRIGHT • IOVATION
AUTHORING AND ADMIN: CUSTOMIZING LAYOUT AND FORMATS
Tailor CSS to different types of users; authors may see entirely different styles than end users, such as template guidance
MindTouch uses Prince XML for PDF
output; deep support for CSS
styling
42© COPYRIGHT • IOVATION 42© COPYRIGHT • IOVATION
AUTHORING AND ADMIN: REPORTING
User activity stats
Search history
Topic ratings, content aging, and full out-of-box integration to Google Analytics
43© COPYRIGHT • IOVATION 43© COPYRIGHT • IOVATION
• Content Design‒ Out of box structured content framework is
smart and thorough but difficult to tailor‒ Logical site design tools are weak
• Workflow is lightweight‒ Draft management is needlessly complex‒ Can’t (yet?) assign content at different stages
of development
CHALLENGES
Q&A
Tanner [email protected]