From Zero to Sixty in Three Seconds (in a Go-kart):
How We Launched a Documentation “Library” on the Web on not Much More than a Shoestring
In just two short years, information developers at Citrix have selected and configured a content management system, converted several document sets to DITA-structured XML, trained multiple writing teams, and formed a new centralized “services and standards” team to lead this effort—all with one overriding goal in mind: to launch a new “documentation library” website. In this article,I’ll explain why we had our eyes on that prize and how we got there.
For many years, documentation teams uploaded PDF documentation to the Support website team’s document management system. For complex products, this process meant that the document set might include as many as 40 PDF guides.
We had been hearing—through customer loyalty surveys and from product managers—that we needed to improve the accessibility and usability of our documentation. The two common themes repeated by customers were:
1. They could not easily find up-to-date technical content about Citrix products on the Citrix website.
2. When they finally did find it, it was a confusing list of separate PDFs with no contextual navigation; customers didn’t know where to start and what to read next. The information on the website is shown as a screen caption in Figure 1.
Another limitation from publishing in PDF format is that while search engines can crawl PDF files, search returns are limited to the entire file. This limitation means that customers searching on a specific term or concept have to open the PDF and then search again within the file.
Customers were demanding an easier, more efficient method of accessing up-to-date technical content from the web. We knew that we could give our customers what they needed if they could just find our content from web searches and navigate their way through it once they got there.
We were confident that if we could produce something tangible—a documentation website—and get the word out to customers, we could start to turn this challenging situation around.
The Challenge: How to Produce a Web Site without Web Developers
We launched a research project to see how others were presenting their product documentation on the web so we could get some ideas to present to our web team.
The examples we liked best were those that used the “library” concept offering a split-pane view with an expandable tree and providing contextual navigation. The back-end technology used by our host web team was not able to support this layout, however. Although the web team did offer to build us a front-end that included some contextual navigation (a simple table of contents structure), the amount of extra work required to upload individual HTML topics to their supporting document management system would in effect negate the efficiencies we knew we would gain from moving to XML and reusing content.
Because we were facing growing requirements to update and add new content on an almost continual basis, we wanted the documentation teams to retain control over the table of contents and library information architecture, something we’d have to give up if we used the front end supplied by the web team. We looked for a way to produce a website straight out of the content management system that we had purchased.
If your team has resident engineering resources or if you can get on the schedule of your engineering department, you might be able to develop compilers internally that will build a web-based site straight out of your CMS. The documentation teams at Citrix have neither, unfortunately, so we needed to keep development work to a minimum.
We had been following with interest the evolution of the documentation “Information Centers” at IBM and were excited to learn that the technology to produce these was readily available from the open-source Eclipse Foundation community. We also knew that the DITA Open Toolkit offered the option to generate “Eclipse Help” output. So we started experimenting. Finally, in December, 2008, we were ready to go live. The result was Citrix eDocs as shown in Figure 2.
What Goes on Behind the Curtain?
The great thing about the Eclipse Help compiler available from the DITA Open Toolkit is that you can generate—out of the box—a robust standalone website that includes:
- A split-pane view; expandable table of contents “tree” on the left with topic content displayed in the right, allowing users to see where they are in the library
- A number of built-in features that increase usability such as node-level printing and bookmarking topics of interest
- Search capabilities allowing customers to search across all topics in the library or limit the search to a subset of topics
- A modular, “plug-in” architecture, allowing you to update content without needing to touch the framework plug-ins
Additionally, controlling the way the content is displayed and organized from within your XML source and being able to automatically add common content to each topic through your style sheet (Google Analytics code or a footer with copyright and trademark information, for example) is a huge time-saver.
However, there are a number of challenges with using the Eclipse Help output to produce a standalone library/site:
- There is not much documentation about producing Eclipse Help-based output. Most of our knowledge has come from trial and error and from posting questions to discussion boards like those on Eclipse.org. (A big shout out to those of you who have answered our questions! Many, many thanks!).
- The split-pane view is created using HTML frames which can be unfriendly to newer web browsers and can make it difficult to share the URL to a specific topic.
- The out-of-the-box styling may not meet your needs and will likely require further style sheet development. We don’t have this expertise in-house so we had to use an outside vendor for our style sheet development.
- The out-of-the-box features, including the toolbar button icons and other graphic elements, seem a bit dated in the Web 2.x world of simple, rounded, sleek, and streamlined as typified by sites like Google and Wikipedia. We have added—again by using outside consultants—several customizations to the out-of-the-box look and feel to reflect more modern design trends.
But, for groups with no access to or influence over your corporate web publishing process, an out-of-the-box solution like Eclipse Help can get you up and running fairly quickly.
Buy Yourselves Some Time—Call it a Beta!
Although we had set a launch date for mid-December 2008, we knew the site would continue to change a lot after that. For example, at that time, only one product team had content in DITA-structured XML and was ready to go into eDocs. We had already identified several additional usability features we wanted to add. Instead of waiting several more months until everything was perfect, we decided to launch the site as a Beta release so we could establish a presence and generate excitement. In addition, calling the site a Beta would allow us to gather feedback from customers and internal groups to see if we were on the right track and gather information about what other features and functionality people wanted.
Traditionally, product documentation teams at Citrix are part of the product development unit, so we don’t have much direct contact with customers. We searched around for ways to get through to customers not only to let them know about the site but to solicit their opinions about it. We found several avenues to achieve our customer input.
Inexpensive or even free online survey tools. We are using SurveyMonkey, where a one-year subscription offering unlimited surveys costs only $200. We created several different “collectors,” which allow us to track where the survey respondents are coming from as shown in Figure 3.
Customer “advisory community.” Citrix had launched a Customer Advisory Community about a year ago. This community comprises more than 70 customers who evaluate our products and provide feedback. We posted documentation-related questions and a link to eDocs to the advisory community. The majority of participants validated that eDocs was an improvement over the way we had published product documentation before. Here are a few select comments from customers:
“The support team here at (a fortune 5 company) applauds the release of this tool. Bravo!”
“Citrix has needed to have a centralized document repository! LOVE IT!!”
“Really makes things much easier and faster to find stuff. Great job!”
“Wow! Great job Citrix! This is really a great start to a resource that I feel will go a long way to helping many of us with a simple and easy solution to the data and information we have been looking for. Great job and can’t wait to see more of it!”
“Knowing that this is out there makes my company more confident in Citrix.”
Google analytics. We had our consultants add Google Analytics code to the style sheet so that it gets embedded into each topic, allowing us to collect statistics about site usage as well as individual topic hits. In the Google Analytics application, we created a filter to separate out hits from within the Citrix corporate network so we could see statistics for customers and for employees. So far, the site statistics are very encouraging. The site averages between 2,000 and 3,000 visits each day on most weekdays from visitors outside the Citrix corporate network. During the month of March, the site had 75,072 visits from 32,577 unique visitors from outside the corporate network.
Lessons Learned So Far
Moving to this entirely new framework of website management is extremely gratifying and a lot of fun. With five months of experience under our belts since we launched the eDocs Beta site, we have learned a great deal:
Develop a publishing “vision” or strategy as early as possible. Citrix often has two to three product lines that share common technology components. What is the best way to represent these products in eDocs? Also, how many product releases should be maintained in eDocs? Some similar online libraries move content to an “Archive” node when a new release comes out. Will this work for you and your customers? Can your CMS support parallel development of product releases and complex versioning?
You need advanced DITA and Eclipse techniques to publish in a streamlined fashion. Our vision for eDocs is to allow a writer or a writing team to update content and push it to the web on a regular basis (we are pushing content live once a week at this point) in as streamlined and automated a way as possible. To achieve this, we now realize we need to break content down into smaller pieces to prevent a situation where an entire documentation set needs to be generated just to update a few topics. However, it’s not easy to find information about advanced techniques, so we are now seeking outside help to develop a strategy.
Customizing Eclipse and the supporting web technologies does cost money. In addition to an initial outlay to develop your style sheet, you may want to add or remove features that come out of the box with Eclipse. Even if you decide to develop in-house XSL skills, you will likely still need to fix bugs or add enhancements, requiring web development skills. Because we don’t have people with these skills in-house, we will likely need to continue to outsource those tasks.
You need someone to host your Eclipse standalone site on a public web server. We were able to get agreement from the Support web team to host the eDocs site and are now working with them on a process to allow us to support continuous publishing.
Your corporate IT groups are not likely to allow the documentation teams unfettered access to public web servers, so you need to find a way to replicate the web server environment for development and testing purposes. Using some of our newest Citrix products, we were able to create a virtual machine that is a near-exact replica of the public web server. Content teams, linguists, and Eclipse experts can upload new content and new code to this virtual machine, test it out, and then push it to the web team’s staging server using a script. Of course, it helps greatly to have scripting expertise in-house.
What’s Next for Citrix eDocs?
Based on the customer and Citrix employee feedback we’ve received, we have a number of big plans in the works for eDocs, including
- Adding a customer feedback form to each topic. We are designing a web form that is attached to each topic and that automatically “passes” data to a back-end bug-tracking database.
- Expanded browser support. The out-of-the-box implementation of the Eclipse-based site does not render well in newer web browsers such as Firefox and Google Chrome. Customers have been very vocal in their requests for improved compatibility with additional browsers.
- Ability to generate PDFs “on the fly” from the HTML. Many of our customers have requested that we offer the content in PDF form as well as HTML.
- We are considering using Eclipse Help for our “in-product” help if it can support the dynamic updating of content from the web as we’ve had many customers request offline access to eDocs.
In closing, we would like to extend our sincere thanks to the CIDM membership, the DITA users group, and the Eclipse Foundation. Many of our ideas and inspiration came from you.
About the Author
Citrix Systems, Inc.
After stints in Boston, New York City, and Washington, DC, Maggie moved to south Florida in 1999 and landed a position at Citrix in 2000. Maggie started as a technical writer at a time when Citrix was beginning to experience massive and rapid growth, adding divisions and R&D sites in several cities around the world. Citrix is now one of the largest high-tech employers in south Florida with additional major R&D sites in Silicon Valley and Boston in the US, the United Kingdom, Bangalore, India, and Sydney, Australia. After serving as manager and director of the largest technical publications team in the company, Maggie, taking inspiration from fellow CIDM members, launched a new team in late 2007—the Documentation Services and Standards team. The team’s overarching mission: to expand XML adoption across all product documentation teams and find a way to easily publish dynamic content on the Web.