This document summarizes the efforts of an insurance company's technical writing team to improve their publishing process. They started with small changes like minimalism and structured authoring. They acquired Arbortext and used it with their existing IBM Document Manager. Their main limitation was their outdated ERIEbooks system. After evaluating options, they created a proof of concept to publish from Arbortext to SharePoint. This provided benefits like search and usage tracking but required more resources than were available. Their next steps are a basic "ERIEbooks Lite" and slowly expanding capabilities in SharePoint.
2. • Where we started
• Small, manageable improvements we implemented
• Publishing alternatives we evaluated
• Proof of concept we constructed
• Struggles and challenges we encountered
Agenda
5/8/2013 2
3. Peeps
Brett McCorkle
– Senior Technical Writer with 8 Years Experience
– Arbortext System Administrator
– Focus on IT Documentation, Diagrams, Standards, etc.
– Bachelors, Management Information Systems
Rita Briody
– Technical Writer II with 5 Years Experience
– Focus on new software and technology
– Bachelors, Political Science, candidate
Master of Science in Computer and
Information Science
5/8/2013 3
4. Who We Are
Company
– Established 1925
– Property/Casualty, Commercial, and Life Insurance
– 11 states and the District of Columbia
Team
– 14 writers in IT Division
– Various backgrounds including
IT, Mathematics, and English
– Experience levels ranging from 2 to 20+
years in technical writing
5/8/2013 4
5. Background
• BookMaster mainframe publishing
• Large monolithic books
– Copious amounts of content
– We documented the features,
not the tasks
• Print and online distribution
• Word documents eventually became the norm
– Developed templates for several document types
– Published as PDFs
• ERIEbooks designed for mainframe docs, not PDFs
5/8/2013 5
6. Approach
• Baby steps!
– Small improvements
over 8 years
• New methods
– Minimalism
– Structured Authoring
• New tools
– Arbortext
– ECM
• ERIEbooks became
our biggest limitation
5/8/2013 6
7. New Methods
• Attended webinars and performed research
– Minimalism
– Structured Authoring
– What the heck is DITA???
• Assigned small groups to provide training to the rest
of the team
– Divide and conquer
– Presentations, working sessions, email newsletters
• Reinforced later with formal on-site training from
ComTech Services
5/8/2013 7
8. New Tools
• Inherited budget from another group to purchase
Arbortext (very, very lucky)
• Controlled our own destiny
– Assigned technical writers with IT backgrounds to configure and
support the tool
• Began a several year effort to manually convert the
content from our legacy systems
• Implemented content management
– The company already owned IBM Document Manager
– Small work requests to prove and implement Arbortext and DM
5/8/2013 8
9. New Capabilities
• Our content is now XML-based
– Began with DITA 1.1, upgraded to DITA 1.2
• Multiple output formats from the same source
– PDF, HTML, EPUB, and online help
• But… we are only publishing to PDF
• Users want more options and better search results
– They are all spoiled by Google
• ERIEbooks, our current delivery system,
is not up to the task
5/8/2013 9
I‟m sorry sir, but I
can„t do that…
10. Benefits
• Minimalism greatly improved our documents
– Action-oriented approach
– Focused on users goals
– Reduced wasteful, repetitive content
• DITA saves us time
– Focus on content, not formatting
– Reuse between documents
– Arbortext creates documents in minutes, not hours (BookMaster)
5/8/2013 10
11. ERIEbooks Problems
• Users are unable to find our documentation
• ERIEbooks, our content delivery system, is very
limited
– Created 15+ years ago as a “temporary solution”
– Pointer system, does not store our content
– Can only reference PDFs and old mainframe documents
– Search limited to document number, title, and 5 keywords
– Limited browsing by subject matter
– No usage tracking or feedback mechanisms
• We must make it easier for users to find the
information they need in the format they want
5/8/2013 11
12. Options
• Do nothing
– Continue using ERIEbooks in its current state (boo!)
• Buy something
– Purchase and implement an off-the-shelf solution ($$$$)
• Dream big
– Build an adapter to connect SharePoint to our source files in IBM
Document Manager
• Use what we already have
– Develop a solution to publish our content to SharePoint 2010 using
Arbortext
5/8/2013 12
13. First Attempt
• We had big dreams
– Big, Hairy, Audacious Goals (BHAGs!)
– Created a wish list of requirements
– Wanted drastic improvements over our current system
• Unrealistic expectations produced few results
– Little progress made for about a year
– Evaluated vendor solutions, all were expensive, none fully met our
lofty requirements
– Worked with internal and external resources to produce a design
that was ultimately unfeasible
• We needed to change our mindset and our approach
5/8/2013 13
14. The Chosen One
• We took a step back and simplified our goals
– Shaved the BHAG!
– Scaled back our wish list
– Reviewed our existing technology
• Focused on the most important requirements
– Modern features: full-text search, usage tracking
– Deliver multiple formats: PDF, HTML, EPUB
– Use tools we already own: Arbortext, SharePoint
– Does not require external resources
• Provides a foundation for future enhancements
5/8/2013 14
15. Design Summary
1. Authors send SOAP requests to the Arbortext
Publishing Engine containing the document ID and
any required parameters
2. Connect to our source repository, IBM Document
Manager
3. Create an HTML version of the requested DITA
document
4. Send a SOAP response with the HTML document
attached
5. Load the document from the SOAP response into
SharePoint, replacing the previous version
5/8/2013 15
17. Proof of Concept
Needed to prove we could:
– Connect the Arbortext Publishing Engine to Document Manager
– Create an interface for SOAP requests
– Send the output to SharePoint
– Eliminate use of out-of-support applications (BookMaster)
5/8/2013 17
18. What We Did
• Three months to complete a proof of concept (POC)
• Connected Arbortext Publishing Engine to DM
– Adapter bundled with Arbortext
– Already in use by writers using Arbortext Editor
• Created interface to submit publish requests
– Began an official POC with our IT Lab (thanks, Rita!)
– Worked with the IT Lab developers to create an application
– Application sends requests to Arbortext and loads the resulting
document into SharePoint
5/8/2013 18
19. Challenges Faced
• Providing metrics to management
– No usage tracking in ERIEbooks
– Difficult to prove anyone used it
• Generating interest and forming alliances
• Budget and resource limitations
– No money to purchase hardware or software
– Low priority effort, work completed during “down time”
• Lack of necessary skills
– Needed other groups to help develop the solution
• Performance issues
– Needed to upgrade the Publishing Engine server
5/8/2013 19
20. Results
• Successfully proved our design
– HTML content automatically loads into SharePoint
– SharePoint returns full-text search results of our content
• Benefits from SharePoint features
– Full text search with in-line results
– Usage tracking
– Versioning
– Personalization (through Active Directory)
• Overwhelming management support
– Approved project to implement our design
– Obtained estimates from required company resources
5/8/2013 20
21. Reality Check
• Budgets and corporate priorities don‟t always directly
support our goals, we‟re here to support theirs
– Competed with other projects for developer resources
– Lost priority to higher rated initiatives
– Placed on hold indefinitely
• The need to replace our archaic system still exists
– We have simplified our approach again
– Still using SharePoint while showing we are adaptable to limited
company resources
• New approach lays the ground work for future
enhancements
5/8/2013 21
22. What‟s Next?
• Continue our Baby Steps journey
• Implement ERIEbooks “Lite”
– Start simple: Replicate ERIEbooks
– Remove existing limitations
– Perform usage tracking
• Goals
– Help our users find what they‟re looking for
– Demonstrate innovation using SharePoint to the company
• Slowly implement additional features
– Publish our content in SharePoint
– Provide full text search, personalization, etc.
5/8/2013 22