Ditching the Desktop: One Vendor's Leap to Hosted Documentation

@Speaker #LavaCon

Ditching the DesktopOne Vendor ’s Leap to Hosted Documentat ion

Tanner VolzTechnical Content Manager, iovation

[email protected]

mailto:[email protected]

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


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


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


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


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


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


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.


Act 2The Hero’s Journey(the 3 act metaphor is a little strained at this point)


• 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



• 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…


• 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 …


• 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


ENTER HOSTED DOCUMENTATION SERVICES!


• 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?


• 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)


• 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


• 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


• 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)


• 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)


WALKTHROUGH


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


USER EXPERIENCE: HIERARCHICAL NAVIGATION AND BREADCRUMBS

Authors define

organization; MindTouch

auto-generates

all navigation


USER EXPERIENCE: RELATED TOPICS, META-TAGS


USER EXPERIENCE: SEARCH

Users can filter and sort

results, as well as enter

advanced search criteria


USER EXPERIENCE: CUSTOM PDF BUILDER

Click a button…

Choose content…

Get a fully formatted

manual with headers, footers,

cover pages…


USER EXPERIENCE: CUSTOM PDF BUILDER (CONT’D)

Tables of content…


USER EXPERIENCE: CUSTOM PDF BUILDER (CONT’D)

And PDF-specific

formatting, all

generated automaticall

y from the HTML

source using custom CSS


USER EXPERIENCE: CONTENT FEEDBACK

Users can rate pages…

And send feedback; we

are notified via email


USER EXPERIENCE: DOWNLOAD SOFTWARE

Users complete a

form and accept a

license agreement to request

software downloads;

we are notified via

email


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


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


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


AUTHORING AND ADMIN: TRACKING CHANGES AND VERSIONS

Detailed revision history

Robust comparison and reversion


AUTHORING AND ADMIN: MANAGING ACCESS AND USERS

Target any content to any user, either individual or in groups


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


AUTHORING AND ADMIN: REPORTING

User activity stats

Search history

Topic ratings, content aging, and full out-of-box integration to Google Analytics


• 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]

Documents

Ditching the Desktop: One Vendor's Leap to Hosted Documentation