Publishing APIs

A company uses XEP for publishing an internal Application Programming Interface (API) specification. XEP replaced Microsoft Word in the publishing toolchain. Here is the story:

Problem

In former times our API was held in a Microsoft Word document. This was then later published to other related departments for their edification. Over the years it grew, became unwieldy and to our horror was being modified outside of our control. At this point we changed to distributing a PDF version, easily read, transported and not so easily edited. . . The difficulty with using Word to hold API specifications are two-fold. Firstly, translation of interfaces into headers files suitable for the compilation system was a by hand function with typical consequences. Cut and Paste failures were frequent and not easily detected. The second difficulty associated with Word is the fact that it is not suited for automatic generation of test patterns.

Solution

Herald the XML way! The word document was saved as text and then carved up using awk into an XML document. From there some basic stylesheets were written which converted the XML into header files, at a stroke future cut and paste failures vanished. (The old were, of course, still there — only much more insidious. But that's another tale.) The new format (XML) now carried another advantage, it allowed us to generate our own test cases directly and generate other ancillary files. It was not though suitable for distribution, end user readable, nor easy to traverse.

Bring on DocBook! A clever stylesheet was written which converted the XML into DocBook format from Norman Walsh, and then using yet more stylesheets converted into HTML. This opened up a new direction, we could markup the original document so that it was both human-readable (via browser) and traversable in a sensible way. Customers (other departments in this case) though are never happy, they wanted and must have the old familar (and printable) PDF version. That is where XEP solved our biggest headache. We produced a PDF specification in the new corporate branding with all the correct information inside.

Radical, and at the same time, the original source XML file has had a small make over: a few important details (e.g. error messages) have been translated into other languages. All held in the same place, readily converted into formats used by the help system, compilation system, and fed through XEP into PDF readily consumed by our greedy customers, who incidentally love the fact we can supply this document on a more periodic basis than the irregular once every six months when we found the inclination/coercion/beer to crunch the buttons.

Finally, a word in closing, this has not been a very cheap (in terms of time) process, but quality and reliability have never come without cost. It has been a very rewarding journey and more importantly opened up even more possibilities than were originally foreseen. For me, the source of beer has dried up, XEP can be controlled from a command line and no longer requires the costly human intervention demanded by Word. Naturally, the source XML document still contains some gremlins (former cut and paste failures) and they must have beer before they can be fixed.