14 Responses to Structured Writing is not Desktop Publishing plus Angle Brackets

  1. Sarah O'Keefe 2011/12/12 at 14:08 #

    Mark, thank you for your eloquent dissection. I thought the tone of the article bordered on inappropriate (especially the part about competitors “maybe” lying).

    The critical question is not “can FrameMaker do XML?” but rather “is FrameMaker the best way to do XML?” For some organizations, perhaps yes. For others, definitely no.

    • Mark Baker 2011/12/12 at 21:50 #

      Hi Sarah, thanks for the comment.

      Agreed about the question. And it is not a question that necessarily has a single enterprise-wide answer. The key to getting good data is to present an interface to the author that is appropriate to them, and to the kind of information you want from them. Thus the bank uses one interface for their ATMs, another for their on-line banking, another for their tellers, and yet another for their loan officers. All contribute information to the accounts of their customers, but in different circumstances, for different purposes, and from people with different levels of knowledge and training.

      As we writers never tire of explaining to developers of the products we document, you have to get the interface right for the job you want people to perform.

  2. Sarah O'Keefe 2011/12/12 at 15:40 #

    I should clarify the tone of the OTHER article, not yours…

  3. Larry Kunz 2011/12/12 at 15:41 #

    Excellent article, Mark. Structured authoring, when done right, follows a database model and doesn’t take into account what the published document will look like. Well said!

    One minor point of disagreement: there is a use case for XML editors that present a DTP facade over an XML schema — because some content contributors, notably SMEs, simply won’t use anything else. However, these editors should be selected with care so that they’re watertight (i.e., the schema can’t be broken). And they probably shouldn’t ever be the primary authoring tool.

    • Mark Baker 2011/12/12 at 21:59 #

      Thanks for the comment, Larry.

      Actually, I don’t disagree that the DTP facade can sometimes be appropriate, if it is the interface that works best for a particular contributor, and you are not asking them for any semantics that cannot be represented that way.

      That said, I have had more success getting reluctant contributors to fill in forms than to use structured editors. With software developers I have been able to get good results asking them to produce raw XML. The key is, you can’t ask them to comply with some complex publishing oriented schema — it just has too much noise for them. You have to give them a schema that works essentially like a form, with nothing extraneous, everything clearly labeled in terms they understand, and little of nothing that is optional.

      This can go a little beyond presenting a different interface over the same schema. In some cases, you have to write a schema specific to the people you want to collect a certain type of data from, then transform that data appropriately as you bring it into your publishing system. I have even created non-XML entry formats on occasion — anything to get good data in.

  4. Eddie VanArsdall 2011/12/12 at 20:55 #

    Mark, I echo the thanks. I’ve been trying to get this point across for the last few days, and now all I have to do is refer people to your excellent post.

    • Mark Baker 2011/12/12 at 22:01 #

      Hi Eddie,

      Thanks for the comment. I’d love an update on how things go with the people you are trying to convince. I’m always looking for better ways to make the case, and to anticipate any confusion or objections people may have.

  5. Antoinne 2011/12/13 at 08:05 #

    Hi Mark, really enjoyed reading your article, especially your thoughts on a good xml editor. I was at Online Information 2011 @ Olympia last week and came across a product called Liquid XML Studio (http://www.liquid-technologies.com/xml-editor.aspx) which I thought was a fairly good xml editor, do you have any particular preferences yourself?

    • Mark Baker 2011/12/13 at 11:20 #

      Hi Antoinne,

      I prefer different editors for different tasks. For writing and for schema design, I use Oxygen. For XSLT work I use jEdit, which is not properly an XML editor, but a text editor with really good XML editing capabilities. Among other things, it has much better syntax highlighting than oXygen. Oxygen uses the same syntax highlighting for all XML documents, whereas the jEdit uses XSLT-specific highlighting, which makes all the difference in the world when programming. It is all a matter of horses for courses.

      Liquid XML lost me right out of the gate because when I downloaded their trial version, I found it was crippled and would not display modular schemas. This is silly, because I don’t evaluate tools against dinky projects, I test them against my normal work. From their website, I see they have changed that policy now, but I don’t have any pressing reason to evaluate them again.

      • George Bina 2011/12/14 at 11:04 #

        Hi Mark,

        Please check the next oXygen release for XSLT work – we added XPath syntax highlighting inside XSLT attributes and indeed that helps a lot. This is planned for early next year but if you want early access just let me know.

        Regards,
        George

        • admin 2011/12/15 at 13:28 #

          Thanks George, I may take you up on that offer, and I certainly look forward to seeing the feature in the next release. You guys should really take a close look at the XML and XSLT syntax coloring in jEdit. It’s the best I have seen.

  6. Richard Rabil, Jr. 2012/01/20 at 16:33 #

    Thanks for this article, Mark. Very useful and insightful.

Trackbacks/Pingbacks

  1. FrameMaker is a real DITA editor…a very poor one | Ditanauts - 2012/01/10

    […] Anti-FrameMaker from Mark Baker […]