If you're a content publisher and use Jive, you've probably thought about whether you could make better use of Jive as a publishing platform. As the leader of Jive's technical documentation team, I've been thinking about this a long time. It's not that I don't believe in Jive for docs teams: I do! See Why Technical Documentation Needs Jive for details on how Jive helps us build technical information every day. That's why every time a customer or prospect has asked me SOOOOO, ARE YOUR DOCS IN JIVE? WHY NOT? over the years, I died a little inside. The fact is, we've been publishing in HTML webhelp, and PDF, but not in Jive. Until now.
It's with great pleasure and a lot of gratitude to Libby Taylor, Ben Walker, David Bastedo, kev.williams, sid.bos, Melanie Jennings, and Leona Campbell--and especially to Suite Solutions, who provided the technology to get this done--that I can announce that we're starting to eat our own delicious Jive-brand dog food. Look right here to see the 8.0 Admin Guide in Jive format, with full Jive functionality!
(That's Jiver dog Pickle demonstrating.)
Why Didn't We Do This Before?
Jive has made amazing progress toward supporting content authors, and we're making more all the time--we've added bulk upload, content sets, improved place curation and many other features in the last year and we're planning to ship more bulk content features in 2016. However, for documentation at scale (we publish more than 1000 topics for each version, and we know many customers have many more), we still have the following challenges, and we know some of our customers share them:
- We need robust version control across many files
- We EXTENSIVELY reuse content across versions and editions--our source is DITA XML, so we do that with a combination of branching, tagging, build-time filtering, and content referencing. There isn't currently a way to do that in Jive. We reuse content not only at the topic level, but down to the level of steps and table cells.
- We need a hierarchical table of contents and inter-document linking that survives updates, because we have many topics and long-form content in chapters.
- We need to be able to create multiple outputs from the same source.
Imagine you need to insert an identical legal notice in 45 out of 300 documents you've posted. . . somewhere in a space. Or that you need to find all the references to available bandwidth and change them by one digit--these are the kinds of updates that tech docs does routinely. In our XML editor, the first operation is a simple one-file update followed by a rebuild, and the second is a simple search-and-replace operation. Did we screw that up? Oops, let's just revert that whole change in SVN.
In Jive. . . search for some string in the content, open each doc individually, cut, paste, save--oh no, I missed a doc someone put in a different space. How did that happen? Wait, Legal changed the wording! I have to do it all over! Separately in each one of those 45 documents! This isn't scalable past a certain point.
The Solution: Write in DITA, Publish in Jive
Nope, we were not giving up our XML source--it just provides too much freedom and functionality. However, we have long thought that it would be useful to publish docs in Jive--provided we were able to write and maintain them with all that great document management functionality Jive doesn't (yet) have. This became a reality quite recently when Suite Solutions wrote a connector that transforms DITA XML content into HTML and injects it into a place in Jive--creating a hierarchical, interlinked document set complete with an auto-generated Table of Contents and breadcrumbs. It even gets automatically marked "Official"! Voila--we create a versioned, semantically tagged source in DITA XML, and we can publish the content in three ways: as HTML5 webhelp (our regular docs at docs.jivesoftware.com), in PDF (embedded in the HTML docs for customers who like a print-like presentation), and as JIVE DOCUMENTS IN JIVE COMMUNITY, with the full Jive capability of sharing, commenting, rating, analytics, and so on.
Here is a sample topic screenshot. Note the breadcrumbs showing the hierarchy at the bottom. These links, as well as section TOCs, are auto-generated based on the hierarchy of our source files. You'll also see that internal cross-references are neatly converted to be links between Jive documents. You'll see version information at the top right of the file: every time we ship a new inline of Jive 8, or add a significant update, we'll overwrite each document in place, preserving any comments and other information just as if we edited and re-saved it manually instead of running a script.
And here's what the nice searchable TOC page looks like. It's auto-generated from the same table of contents file we use for the HTML5 version of the 8.0 Admin docs (but here, it's expanded).
How Does the Magic Happen?
A folder gets added to the DITA Open Toolkit (an open-source library we used to transform DITA XML files into living, breathing docs). This folder is integrated with the toolkit and uses custom XSLT to create a Jive-ready output. We then install an add-on in the destination community that will provide authentication access to post files using the REST API. Finally, we run a build script against the Jive Online Documentation ditamap (a hierarchical list of files that's also used to create our other documentation formats) that builds the Jive-format files from the latest content checked into our SVN repository, and posts them in the destination community.
So, What's the Plan?
Currently, we only have the Jive 8 admin docs out in Community. Ben Walker has connected the typeahead search in Supportal to pop up our Jive-format documentation (along with KB articles) when you start typing a case description, which should get you to relevant docs faster! We already have showing statistics showing Support case deflection based on reading documentation articles.
We also recommend bookmarking the Jive 8 Community Administration Help space for easy searching. The Documentation team monitors this space and will respond to comments on documentation topics, so feel free to put your questions and comments there as well as sharing, bookmarking, and linking these docs in Community.
Deploying multiple versions of the same content in a Jive community is raising some questions about search, but stay tuned for more products, editions, and versions to have docs in Jive soon. Happy reading and keep on Jiving!