The Sphinx Kool-Aid Looks Great…But I Don’t Want to Drink It

After 16 years using XML, I’ve been tempted to switch to Sphinx. My new colleague at Eucalyptus, Kushal Das ( , has asked me to think about switching our DITA content to reStructuredText (reST).

I tried Sphinx last year at the Write the Docs conference. It’s pretty impressive, especially in that it’s lightweight. This is a big plus in terms of our community. Currently, anyone who wants to contribute content has to fork a h-u-g-e repository that includes tons of tools necessary to generate content.

It’s not pretty.

However, XML offers so much…that and I hate change. However, if it benefits our community, I’m willing to use crayons and paper cocktail napkins.

Have you gone from XML to reST? If so, please let me know what benefits you found.

About scotmarvin

Scot is an editor and writer involved in content design, content architecture, big data, cloud computing, and other buzzwords related to technical stuff. He loves his family, history books, jazz guitar, and the Minnesota Vikings. Scot is a proud father, so don't make the mistake of asking about his family unless you have four hours to listen to him ramble on about his kids.
This entry was posted in documentation. Bookmark the permalink.

5 Responses to The Sphinx Kool-Aid Looks Great…But I Don’t Want to Drink It

  1. mbakeranalecta says:

    I have been a structured writing stalwart for a long time (since before XML was a thing) but more and more these days I think that structured writing as it is currently practiced is just too complex to ever catch on outside a small niche of full time technical writers.

    reST and Markdown show that markup per se is not the stumbling block. But I think the verbosity of XML and the complexity of current standards such as Docbook and DITA are stumbling blocks.

    I believe it is possible to make structured writing much simpler than it is now — potentially simple enough to be useful to a much wider audience. I’m looking for some like-mined folks to kick around some ideas with.

  2. scotmarvin says:

    Interesting, Mark. Do you think it’s the number of elements in DITA? (We won’t go into the hundreds of Docbook elements.) Or is it the transformation of the XML into generated media? Both? I’m curious what you think is too complex. I’m not saying you’re wrong. You very well might be right. I’ve been hanging out, waiting for everyone else to drop Framemaker, Flare, Word, or whatever, and come on over to XML. There are certainly more than when I started using it, but not as much adoption as I would have hoped.

  3. mbakeranalecta says:

    For writers, I think the issue with both DocBook and DITA is that you simply have to know too much — not just tags, but the concepts behind them. It’s rather like FrameMaker vs. Word. FrameMaker is very powerful, but you have to know a lot of stuff about Frame’s model of a document. These are not tools for part time and occasional authors.

    With XML, I think the problem is that we have not succeeded in developing a way to show the structure while hiding the tags. You can write using a WYSIWYG view, but trying to cut and paste content around, or edit an existing document can be very difficult. Try to paste something where it is not supposed to go, and you have to sort out some really obscure error messages. This forces many writers to switch to the tags view to edit effectively — which gets you back to having to understand XML.

    It is worth noting that XML has already been replaced by simpler formats for the roles it was originally supposed to play on the Web. For data exchange between applications, it has been replaced by JSON. For semantic markup of Web pages, it has been replaced by HTML5 and microformats.

    I suspect that we may similarly need something simpler if we want to spread structured writing much beyond full time tech writers. There is a huge gap in sophistication and complexity between Markdown and reST on the one hand and XML on the other. Maybe there is room in the middle for something simple yet semantic.

  4. scotmarvin says:

    Well, that gives me hope. It will be interesting to see what pops up. There are a number of issues wit reST that my frenemies over at Rackspace/OpenStack pointed out. I respect what they have to say, and their rationale against reST gives me pause. However, we’re still going to do a pilot project with it and test it. We’ll see if enough community folks like it enough to start contributing more content.

    My fear is that, after I finish reading your book, I’m going to find that all my elaborate architecture will taunt me and I’ll find that plain text is the way to go. I’ll be publishing a series of readme.txt files for installation and configuration. (shudder)

  5. mbakeranalecta says:

    Well, I hope that after you have finished reading my book, you will find that the right way to go is to create well structured Every Page is Page One topics that are related to each other through rich, non-hierarchical links.

    One of the issues I have with the current practice of structured writing is that it is founded in the structures of 20th century information products (books and captive help systems). This model is chiefly a top-down structure that cares more about the order and subornation of items in the hierarchy than about the structure of the individual items.

    In an Every Page is Page One world, the structure of the individual items matters more because each item has to work on its own and each item has to have a very clear information scent to appeal to readers who can very easily move on. Also the rich linking that an Every Page is Page One information set requires can be generated from the metadata of well structured individual topics.

    As a bonus, well structured topics that work in a hypertext network can also be successfully organized into a hierarchical book or help systems (which some do still need to deliver). Nor is there anything wrong with putting a hierarchical organization around your topics as long as they also work well when navigated from the bottom up. But a monster hierarchy that scares the reader out of even attempting to use the documentation set is clearly to be avoided.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s