Loading ...
Sorry, an error occurred while loading the content.

Rant: Is XML for documentation going the way of SGML? (long)

Expand Messages
  • Larry Kollar
    This rant probably won t be well-received here (or maybe I m preaching to the choir), but I think it needs to be said -- and then discussed, if we are to avoid
    Message 1 of 29 , Jan 20, 2005
    • 0 Attachment
      This rant probably won't be well-received here (or maybe I'm
      preaching to the choir), but I think it needs to be said -- and then
      discussed, if we are to avoid seeing XML sink into irrelevance as a
      documentation format. (As an *interchange* format, XML is well-
      established and in no danger of losing relevance, and that's all I
      think needs to be said there. :-)

      The "SGML era" can be said to run from 1980 to early 1998 (when
      XML 1.0 was formalized). For most of that time, SGML was found
      primarily in the military supply and aerospace industries, with
      a few probes from academia and curious gearheads. Outside of
      heavy industry DTDs, I can think of only DocBook and TEI (and
      HTML, but I'll hit that next) that have anything resembling
      widespread use today, and I'd wager that many people who are
      familiar with DocBook haven't heard of TEI.

      The introduction of the HTML-driven World Wide Web in 1991/1992
      prompted many of us who were around at the time to check out
      HTML, and then SGML. Indeed, SGML probably got more attention
      in the first few years of the Web than it had throughout its
      previous history. And what did we find? A great idea -- a
      meta-language for markup -- surrounded by nearly impenetrable
      layers of what could be called support structure.

      Without incredibly complex DTDs (MIL-spec), strange formatting
      languages (FOSI, DSSSL), and databases, how would vendors justify
      six-figure deployment costs and five-figure yearly support
      contracts? SGML by itself was simply too simple to be a big
      money-maker. A university, or a documentation group in a small
      business, would have been able to use a DTD of middling complexity
      and a way to convert SGML to something like Script (IBM mainframes)
      or troff (Unix), or TeX. But margins for something like that
      weren't big enough, then along came GUIs and word processors.

      It shouldn't have been this way. SGML was designed to be an open
      standard, facilitating interchange between interested parties.
      Nothing proprietary about that, is there? Yet an SGML "solution"
      ended up costing orders of magnitude more than word processors
      using impenetrable binary formats. And outside those heavy
      industries that could afford the price tag, SGML became "Sounds
      Great, Maybe Later" and sank into obscurity.

      Then came HTML, truly the people's DTD. For all the ragging HTML
      gets, it gave SGML a spotlight and got enough people interested
      in creating XML.

      Shortly after XML appeared came XSL, a highly complex transformation
      and formatting language that was quickly broken into XSLT and
      XSL-FO components. And we have XPath (another amoeba-like split
      of XSLT), XSchema, XQuery, SOAP, etc. More layers, many of which
      are fortunately geared toward the interchange side of things rather
      than documentation.

      So what's the problem? In a word, attitude.

      The first problem is the attitude of "everything must be XML"
      once again leads us down the path of ignoring perfectly workable
      (and free, in most cases) technologies in favor of "solutions"
      that add expense and complexity and give little or no gain in
      return. Seriously, what does XSL-FO do that TeX or Groff can't?
      I know for sure I can define a page layout in Groff using a lot
      fewer lines of code than I could in FO.

      The second problem is the attitude of many technical writers,
      who are simply sitting back and waiting for a shrink-wrapped
      XML "solution" instead of proactively building something that's
      easy to implement and flexible enough to meet whatever our needs
      may be. If we wait for the vendors to give us *their* solution,
      we'll be right back to the days of six-figure implementation
      and five-figure support costs -- and XML (as a documentation
      tool) will become "eXcellent, Maybe Later" and join SGML in
      obscurity.

      It doesn't have to be that way. Not only is XML just as open
      (if not more so) than SGML, a plethora of Free, Open Source,
      and low-cost commercial tools have grown up around it or have
      been adapted to work with it. The pieces are lying all around
      us, like several model car kits all jumbled together. We need
      to start picking up pieces, fit them together, and start applying
      glue and paint.

      Needless to say, this is my personal opinion and not necessarily
      that of my employer.

      --
      Larry Kollar, Senior Technical Writer, ARRIS
      "Content creators are the engine that drives
      value in the information life cycle."
      -- Barry Schaeffer, on XML-Doc
    • Alexander Witzigmann
      i think you missed the real intention using sgml / xml as source format for your technical documentation. you try to divide content from its representation and
      Message 2 of 29 , Jan 20, 2005
      • 0 Attachment
        i think you missed the real intention using sgml / xml as source format
        for your technical documentation.
        you try to divide content from its representation and thats just based
        on standardized format.
        i've seen lots of small companies using sgml. just using a "proprietary"
        dtd, corresponding stysheets for well known editors and mature
        publication processes to html / pdf / html-help ....
        i think thats the benefit you got from sgml / xml -> write once /
        publish everywhere ;-). getting a common data structure covers all
        use-cases around is really impossible and not intent by sgml / xml
        community. only concepts may be reusable. architectural frameworks like
        DITA (http://www-106.ibm.com/developerworks/xml/library/x-dita1/) coming
        from this direction. just a bunch of concepts, corresponding
        implementation to start from.

        your right, this approach always costs some money to implement, but much
        less if you based on standards - inventing your own format to get
        content representation costs much more effort or is nearby impossible.

        alex


        Larry Kollar wrote:

        >This rant probably won't be well-received here (or maybe I'm
        >preaching to the choir), but I think it needs to be said -- and then
        >discussed, if we are to avoid seeing XML sink into irrelevance as a
        >documentation format. (As an *interchange* format, XML is well-
        >established and in no danger of losing relevance, and that's all I
        >think needs to be said there. :-)
        >
        >The "SGML era" can be said to run from 1980 to early 1998 (when
        >XML 1.0 was formalized). For most of that time, SGML was found
        >primarily in the military supply and aerospace industries, with
        >a few probes from academia and curious gearheads. Outside of
        >heavy industry DTDs, I can think of only DocBook and TEI (and
        >HTML, but I'll hit that next) that have anything resembling
        >widespread use today, and I'd wager that many people who are
        >familiar with DocBook haven't heard of TEI.
        >
        >The introduction of the HTML-driven World Wide Web in 1991/1992
        >prompted many of us who were around at the time to check out
        >HTML, and then SGML. Indeed, SGML probably got more attention
        >in the first few years of the Web than it had throughout its
        >previous history. And what did we find? A great idea -- a
        >meta-language for markup -- surrounded by nearly impenetrable
        >layers of what could be called support structure.
        >
        >Without incredibly complex DTDs (MIL-spec), strange formatting
        >languages (FOSI, DSSSL), and databases, how would vendors justify
        >six-figure deployment costs and five-figure yearly support
        >contracts? SGML by itself was simply too simple to be a big
        >money-maker. A university, or a documentation group in a small
        >business, would have been able to use a DTD of middling complexity
        >and a way to convert SGML to something like Script (IBM mainframes)
        >or troff (Unix), or TeX. But margins for something like that
        >weren't big enough, then along came GUIs and word processors.
        >
        >It shouldn't have been this way. SGML was designed to be an open
        >standard, facilitating interchange between interested parties.
        >Nothing proprietary about that, is there? Yet an SGML "solution"
        >ended up costing orders of magnitude more than word processors
        >using impenetrable binary formats. And outside those heavy
        >industries that could afford the price tag, SGML became "Sounds
        >Great, Maybe Later" and sank into obscurity.
        >
        >Then came HTML, truly the people's DTD. For all the ragging HTML
        >gets, it gave SGML a spotlight and got enough people interested
        >in creating XML.
        >
        >Shortly after XML appeared came XSL, a highly complex transformation
        >and formatting language that was quickly broken into XSLT and
        >XSL-FO components. And we have XPath (another amoeba-like split
        >of XSLT), XSchema, XQuery, SOAP, etc. More layers, many of which
        >are fortunately geared toward the interchange side of things rather
        >than documentation.
        >
        >So what's the problem? In a word, attitude.
        >
        >The first problem is the attitude of "everything must be XML"
        >once again leads us down the path of ignoring perfectly workable
        >(and free, in most cases) technologies in favor of "solutions"
        >that add expense and complexity and give little or no gain in
        >return. Seriously, what does XSL-FO do that TeX or Groff can't?
        >I know for sure I can define a page layout in Groff using a lot
        >fewer lines of code than I could in FO.
        >
        >The second problem is the attitude of many technical writers,
        >who are simply sitting back and waiting for a shrink-wrapped
        >XML "solution" instead of proactively building something that's
        >easy to implement and flexible enough to meet whatever our needs
        >may be. If we wait for the vendors to give us *their* solution,
        >we'll be right back to the days of six-figure implementation
        >and five-figure support costs -- and XML (as a documentation
        >tool) will become "eXcellent, Maybe Later" and join SGML in
        >obscurity.
        >
        >It doesn't have to be that way. Not only is XML just as open
        >(if not more so) than SGML, a plethora of Free, Open Source,
        >and low-cost commercial tools have grown up around it or have
        >been adapted to work with it. The pieces are lying all around
        >us, like several model car kits all jumbled together. We need
        >to start picking up pieces, fit them together, and start applying
        >glue and paint.
        >
        >Needless to say, this is my personal opinion and not necessarily
        >that of my employer.
        >
        >--
        >Larry Kollar, Senior Technical Writer, ARRIS
        >"Content creators are the engine that drives
        >value in the information life cycle."
        > -- Barry Schaeffer, on XML-Doc
        >
        >
        >
        >Yahoo! Groups Links
        >
        >
        >
        >
        >
        >
        >
        >
        >
      • Camille Bégnis
        Hi Larry and all, and thanks for this rant, I think you are expressing in words, a profound but vague bad feeling I myself have had buried inside for years.
        Message 3 of 29 , Jan 21, 2005
        • 0 Attachment
          Hi Larry and all,

          and thanks for this rant, I think you are expressing in words, a profound but
          vague bad feeling I myself have had buried inside for years.

          On Thursday 20 January 2005 21:26, Larry Kollar wrote:
          > This rant probably won't be well-received here (or maybe I'm
          > preaching to the choir), but I think it needs to be said -- and then
          > discussed, if we are to avoid seeing XML sink into irrelevance as a
          > documentation format. (As an *interchange* format, XML is well-
          > established and in no danger of losing relevance, and that's all I
          > think needs to be said there. :-)

          [...]

          > The second problem is the attitude of many technical writers,
          > who are simply sitting back and waiting for a shrink-wrapped
          > XML "solution" instead of proactively building something that's

          What is this "something" you have in mind?

          > easy to implement and flexible enough to meet whatever our needs
          > may be. If we wait for the vendors to give us *their* solution,
          > we'll be right back to the days of six-figure implementation
          > and five-figure support costs -- and XML (as a documentation
          > tool) will become "eXcellent, Maybe Later" and join SGML in
          > obscurity.
          >
          > It doesn't have to be that way. Not only is XML just as open
          > (if not more so) than SGML, a plethora of Free, Open Source,
          > and low-cost commercial tools have grown up around it or have
          > been adapted to work with it. The pieces are lying all around
          > us, like several model car kits all jumbled together. We need
          > to start picking up pieces, fit them together, and start applying
          > glue and paint.

          We've been doing this in our own corner, although without the paint, and I
          guess that's what everyone is doing. Are you suggesting we join forces to
          design the specifications (the "kit erecting instructions") of this
          "something", and then build and paint it?

          --
          Camille Bégnis
          NeoDoc Co-founder
          http://neodoc.biz
        • John Krasnay
          ... Sorry, I just couldn t resist the urge to step in here with a plug for Vex. This is *exactly* the kind of thing I m trying to build: a free, extensible,
          Message 4 of 29 , Jan 22, 2005
          • 0 Attachment
            On Thu, 2005-01-20 at 15:26 -0500, Larry Kollar wrote:

            > The second problem is the attitude of many technical writers,
            > who are simply sitting back and waiting for a shrink-wrapped
            > XML "solution" instead of proactively building something that's
            > easy to implement and flexible enough to meet whatever our needs
            > may be. If we wait for the vendors to give us *their* solution,
            > we'll be right back to the days of six-figure implementation
            > and five-figure support costs -- and XML (as a documentation
            > tool) will become "eXcellent, Maybe Later" and join SGML in
            > obscurity.

            > It doesn't have to be that way. Not only is XML just as open
            > (if not more so) than SGML, a plethora of Free, Open Source,
            > and low-cost commercial tools have grown up around it or have
            > been adapted to work with it. The pieces are lying all around
            > us, like several model car kits all jumbled together. We need
            > to start picking up pieces, fit them together, and start applying
            > glue and paint.

            Sorry, I just couldn't resist the urge to step in here with a plug for
            Vex. This is *exactly* the kind of thing I'm trying to build: a free,
            extensible, XML publishing platform. The main thing that I'm missing is
            input from technical writers: which features are important, which can be
            deferred, how can we improve usability, etc.

            So maybe your call for tech writers to build tools should include a call
            to lend their expertise to some enthusiastic open source developers.

            jk
          • Ambot Sakoy
            Hello Larry. In my case, you re preaching to the choir. There s a divide between large scale documentation shops found in government and document intensive
            Message 5 of 29 , Jan 24, 2005
            • 0 Attachment
              Hello Larry.

              In my case, you're preaching to the choir.

              There's a divide between large scale documentation "shops" found in
              government and document intensive industries like aircraft, and much
              more numerous small groups typical of much of the software industry.

              The former can afford to fly Hockos in for $15k a week to tell them
              that documenation is an enterprise-wide issue that what ever 6-digit
              product plus 5-digit annual fee she is promoting at the time can
              solve, after the 5/6-digit figure is paid to have her favorite
              consulting service come in and set everything up at no small
              disruption to the company. This is the sort of "big thing" top
              executives like to do to demonstrate that they're not allowing their
              company to fall behind the trend towards "intelligent, learning
              enterprises."

              On the other hand, there are thousands of small technical writing
              operations, even peppered among the org charts of big companies, that
              struggle to get by as a "cost of doing buiness." We all know what
              that means - you're an expense to be controlled and minimized.

              In such an environment, the (false) allure of XML is "free tools"
              and "independency from remote, uncaring vendors" like Adobe and
              Microsoft appeals to managers, not to mention is another notch
              of "professional relevancy" on our resumes - you never know when
              you'll be out on the pavement, only that the odds are there.

              If XML for documenation is going the way of SGML, it is because all
              the sound and furry of XML is failing to meet the vendor, paid
              consultant and evangelist hype. For all the effort and struggle, few
              are experiencing a break out into the promised land, just as was the
              case with SGML.

              The reason is simple. Pushing elements around doesn't hold a candle
              to WYSIWYG authoring or web publishing, and it just don't pass a
              beancounters muster; the economics aren't there to justify the effort
              on a cost-benefit basis nor are customers clammering and spending for
              XML, what ever that is from a document user's perspective.

              Please, speak up if you've seen meaningful, benefits that resulted
              from converting to XML. Things like the following would be impressive
              coming from small-medium shops:

              1. Sales of our products doubled when we converted.
              2. Marketing told us we can add a 25% premium to the price of our
              products for going XML.
              3. We are so much more productive under XML that we laid off 30%
              of our staff
              4. Our doc department is now a profit center making money charging
              for our XML documents and selling XML services to our customers.
              5. Editors tell us our documentation is almost flawless now that
              it's in XML.
              6. Customers have been measured 25% more productive because of our
              XML documenation.

              For most, the vision just isn't there, and the utility economics -
              sea changes in how effective documentation becomes or how much the
              cost of producing of information drops - are simply lacking (except
              in large, specialized situations). And, what is becoming increasinly
              clear is the added cost and disruption of rolling in new technology,
              tools and methods in a business that is already stretched thin and
              cost conscious is a challenge with uncertain payoff.

              I love technology, and SGML and XML were the holy grail in terms of
              supporting a way of creating languages that talk about data and
              documents and their contents in a way that software can work with, so
              I'm having fun (that can be important to some managers). But, in all
              honesty, the profession would be much better served by better project
              management that more deeply understands the challenges of technical
              documentation, including the economics of information, than one more
              diversion in a history of diversions.

              That's not to say XML doesn't hold promise; it does. The problem is
              that the profession is a long way from understanding and envisioning
              what that "promise" actually is and how it fits in other
              possibilities. All we know for certain is that the effort and costs
              keep mounting, those damn books never let up, and who knows if
              they'll be employed next month (better make sure that resume has all
              the current buzz words present and accounted for).

              As a certain fatigue sets in, it becomes it's easier to let the
              vendors sort it out. After all, no one was ever fired for buying
              Adobe or Microsoft!

              Where are the academics in all this - the thinking, envisioning wing
              of the profession? With few exceptions, if they're not discussing the
              fine points of M.M. Bakhtin and his relevance to technical
              documenation as an expression of post mondernist sensibilities,
              they're out doing field work collecting "document artifacts" and
              organizing them into "genres" or fooling around with personal
              websites (out) and blogs (in). The subject of "information and
              technical writing economics" remains "getting a monthly paycheck."
              And, true to form, XML appears in endless journal articles about "how
              to make technical writing programs relevant by including it."

              Not to scare anyone but it seems we're on our own kids.

              As always, nice touching base with you again Larry.

              Tim
            • superk
              ... Like Tim said, I also got trapped in the GUI editor features list... This was the core of your message IMHO Larry: waiting for XML editing to be like Word.
              Message 6 of 29 , Jan 27, 2005
              • 0 Attachment
                Larry Kollar wrote:

                > The second problem is the attitude of many technical writers,
                > who are simply sitting back and waiting for a shrink-wrapped
                > XML "solution" instead of proactively building something that's
                > easy to implement and flexible enough to meet whatever our needs
                > may be. If we wait for the vendors to give us *their* solution,
                > we'll be right back to the days of six-figure implementation
                > and five-figure support costs -- and XML (as a documentation
                > tool) will become "eXcellent, Maybe Later" and join SGML in
                > obscurity.

                Like Tim said, I also got trapped in the GUI editor features list...
                This was the core of your message IMHO Larry: waiting for XML editing to
                be like Word. No wonder it got so much attention when MS introduced it's
                supposedly XML Word format (didn't try it, won't either). But the catch
                22 is that writers don't have the time (nor the skills, sometimes) to
                write their own tools, so they rely on big corps like MS and Adobe to
                provide those tools while they think of content (and then again,
                "thinking" is an overstatement, sometimes). By the time an XML solution
                pops up, it means restructuring the documentation department to adapt to
                that wonderful, yet more complex solution.

                > It doesn't have to be that way. Not only is XML just as open
                > (if not more so) than SGML, a plethora of Free, Open Source,
                > and low-cost commercial tools have grown up around it or have
                > been adapted to work with it. The pieces are lying all around
                > us, like several model car kits all jumbled together. We need
                > to start picking up pieces, fit them together, and start applying
                > glue and paint.

                Well... some of us are already doing that, picking up open source
                software and enhancing them to drive documentation at XML speed. Tools
                like Borges, VEX, OmegaT and emacs can *be* that XML solution. Then
                again all those tools are mainly oriented towards the Linux* platforms:
                in that environment, people are less afraid of the new and enigmatic,
                unfriendly app. GUIs are not a must, but appreciated, at most.

                I think it's about open-mindedness (learning new ways to work) and
                education (in school, even at university level, you're not taught to use
                a word processor, or even a text editor, you're asked to use Word, plain
                and simple).

                Stop thinking dummy: write!

                Thx for the rant opening Larry

                K
              • Denis Bradford
                As a writer who has been in the trenches for some time with SGML and XML, I d like to second Larry s excellent point that XML is in danger of going the way of
                Message 7 of 29 , Jan 28, 2005
                • 0 Attachment
                  As a writer who has been in the trenches for some time with SGML and
                  XML, I'd like to second Larry's excellent point that XML is in danger
                  of going the way of SGML.

                  In my experience, vendors work hard to hype buzzwords like "reuse" so
                  they can sell their tools, but are lax when it comes to explaining the
                  serious work that it still takes to use XML. I also agree that many
                  technical writers have an attitude problem: most of the seasoned doc
                  professionals I've worked with are militantly ignorant of anything
                  that would require changing old habits (like giving up shrink wrap).

                  Given the lack of traction among vendors and writers, I'm not
                  surprised that most software companies in my area (Boston) are still
                  FrameMaker/RoboHelp shops. As near as I can tell, XML has been adopted
                  mostly by the same kinds of organizations that embraced SGML: the
                  ones who can afford it. The last XML conference I attended was mainly
                  a venue for consultants to bring together high-end vendors and
                  information managers from large corporations. Far from being concerned
                  about the barriers to wider XML adoption, everybody there seemed
                  pleased to be exclusive stakeholders in a lucrative game. IMO, if this
                  is the dynamic that determines the direction of XML publishing, I
                  think it will be be another long, slow decline into oblivion - because
                  like SGML, it will lack a critical mass of vendors and users.

                  Surely what's different this time around is a vigorous open source
                  community. If the people who are busy creating the core open source
                  systems and apps can keep them open and counterbalance the big funders
                  in driving standards, just maybe the proprietary vendors can be
                  dissuaded from killing the goose that lays the golden egg. If there's
                  hope for the survival of XML publishing, it might be the growing
                  number of companies who are finding ways to accommodate the creative
                  engine that now underpins their entire market.

                  I'm not sure what to do about the attitude of technical writers. If
                  current job trends in that field are any indication, it may be an
                  academic question anyway.
                • barry@xsystems.com
                  Our little firm began developing editorial applications based on SGML 15 years ago and have moved into XML as it became available. I think it can be fairly
                  Message 8 of 29 , Jan 28, 2005
                  • 0 Attachment
                    Our little firm began developing editorial applications based on SGML 15
                    years ago and have moved into XML as it became available. I think it can
                    be fairly said that the standards are not the problem. In fact, it is the
                    human part of the equation that vexes (and has always vexed) us. From
                    tech writing groups that fail to see the wisdom of capturing their
                    intellectual property in a notation (SGML/XML)that maximizes its value; to
                    IT groups that fail to see the differences between the orderly world,
                    bounded by relational technology, and the text world that breaks all of
                    those rules (and decides that the reason for this must be that text people
                    are just undisciplined); to top management that fails to include the value
                    of authors' time and information product value when it calculates the ROI
                    needed to fund text projects; to the software industry that for decades
                    ignored text forms in which most of the world's information is kept, etc.,
                    etc. Perhaps all of this is to be expected. We are in the midst of a
                    massive cultural change in the way we inform ourselves. The last time we
                    went through this major a shift was when we gave up scrolls, available
                    only to the elite who were taught to read them, and reproduced books for
                    the masses whom we began also teaching to read. That took nearly 600
                    years, so perhaps we just need to persevere and understand that we may not
                    see, in our lifetime, the full fruition of what we are trying to do.

                    Regards,

                    Barry

                    http://www.xsystems.com/randomxml.htm"

                    -----------------------------------------------------------------
                    X.Systems, Inc. ...content solutions for the Internet Age
                    703-330-1645 www.xsystems.com
                    -----------------------------------------------------------------



                    superk <chris@...>
                    01/27/2005 09:48 PM
                    Please respond to
                    xml-doc@yahoogroups.com


                    To
                    xml-doc@yahoogroups.com
                    cc

                    Subject
                    Re: [xml-doc] Rant: Is XML for documentation going the way of SGML? (long)







                    Larry Kollar wrote:

                    > The second problem is the attitude of many technical writers,
                    > who are simply sitting back and waiting for a shrink-wrapped
                    > XML "solution" instead of proactively building something that's
                    > easy to implement and flexible enough to meet whatever our needs
                    > may be. If we wait for the vendors to give us *their* solution,
                    > we'll be right back to the days of six-figure implementation
                    > and five-figure support costs -- and XML (as a documentation
                    > tool) will become "eXcellent, Maybe Later" and join SGML in
                    > obscurity.

                    Like Tim said, I also got trapped in the GUI editor features list...
                    This was the core of your message IMHO Larry: waiting for XML editing to
                    be like Word. No wonder it got so much attention when MS introduced it's
                    supposedly XML Word format (didn't try it, won't either). But the catch
                    22 is that writers don't have the time (nor the skills, sometimes) to
                    write their own tools, so they rely on big corps like MS and Adobe to
                    provide those tools while they think of content (and then again,
                    "thinking" is an overstatement, sometimes). By the time an XML solution
                    pops up, it means restructuring the documentation department to adapt to
                    that wonderful, yet more complex solution.

                    > It doesn't have to be that way. Not only is XML just as open
                    > (if not more so) than SGML, a plethora of Free, Open Source,
                    > and low-cost commercial tools have grown up around it or have
                    > been adapted to work with it. The pieces are lying all around
                    > us, like several model car kits all jumbled together. We need
                    > to start picking up pieces, fit them together, and start applying
                    > glue and paint.

                    Well... some of us are already doing that, picking up open source
                    software and enhancing them to drive documentation at XML speed. Tools
                    like Borges, VEX, OmegaT and emacs can *be* that XML solution. Then
                    again all those tools are mainly oriented towards the Linux* platforms:
                    in that environment, people are less afraid of the new and enigmatic,
                    unfriendly app. GUIs are not a must, but appreciated, at most.

                    I think it's about open-mindedness (learning new ways to work) and
                    education (in school, even at university level, you're not taught to use
                    a word processor, or even a text editor, you're asked to use Word, plain
                    and simple).

                    Stop thinking dummy: write!

                    Thx for the rant opening Larry

                    K



                    Yahoo! Groups Links










                    [Non-text portions of this message have been removed]
                  • barry_schaeffer
                    Our little firm began developing editorial applications based on SGML 15 years ago and have moved into XML as it became available. I think it can be fairly
                    Message 9 of 29 , Jan 28, 2005
                    • 0 Attachment
                      Our little firm began developing editorial applications based on SGML
                      15 years ago and have moved into XML as it became available. I think
                      it can be fairly said that the standards are not the problem. In
                      fact, it is the human part of the equation that vexes (and has always
                      vexed) us. From tech writing groups that fail to see the wisdom of
                      capturing their intellectual property in a notation (SGML/XML)that
                      maximizes its value; to IT groups that fail to see the differences
                      between the orderly world, bounded by relational technology, and the
                      text world that breaks all of those rules (and decides that the
                      reason for this must be that text people are just undisciplined); to
                      top management that fails to include the value of authors' time and
                      information product value when it calculates the ROI needed to fund
                      text projects; to the software industry that for decades ignored text
                      forms in which most of the world's information is kept, etc., etc.
                      Perhaps all of this is to be expected. We are in the midst of a
                      massive cultural change in the way we inform ourselves. The last
                      time we went through this major a shift was when we gave up scrolls,
                      available only to the elite who were taught to read them, and
                      reproduced books for the masses whom we began also teaching to read.
                      That took nearly 600 years, so perhaps we just need to persevere and
                      understand that we may not see, in our lifetime, the full fruition of
                      what we are trying to do.

                      Regards,

                      Barry
                    • Ambot Sakoy
                      Peter Ring and Denis Bradford both noted that the open source community surrounding XML is what is different than SGML (let s include the Frame document object
                      Message 10 of 29 , Jan 28, 2005
                      • 0 Attachment
                        Peter Ring and Denis Bradford both noted that the open source
                        community surrounding XML is what is different than SGML (let's
                        include the Frame document object model too). I was around in the
                        1980s and there was a community then who also responded to the
                        potential of markup languages although there wasn't the open
                        landscape that the web afforded XML.

                        SGML became "captured" by big, deep pocket interests - Barry noticed
                        signs of this happening at XML conventions. An open community is no
                        guarentee of that not happening with XML if it fails to result in
                        solutions that directly address the primary charter of technical
                        documentation shops - quick, on demand, spot on information through
                        good writing and appropriate technology at stable to reduced cost.

                        XML/SGML is relevant only as far as it helps fulfill the entire
                        charter.
                        Currently, except for a few large scale, specialized situations, there
                        is scant evidence that it does, especially in small shop settings that
                        characterize more technical writing organizations.

                        On reason is that technological change rarely succeeds without
                        organizational changes, and the sophistication of most technial
                        writing managers is inadequate even for current methods. Inventory
                        mangement, for example, is crude and light years away from the
                        management of topics.

                        The same is true of the prevailing view of "meta data" as paragraphs
                        and inline markers for "code" and a few types based on purpose
                        (reference, instructions, concept). No where to be seen is thinking
                        about language that describes the content of a product. For example,
                        how do I say the following in DocBook?

                        SOFTWARE > API > DATABASE > CONNECTION

                        Wouldn't I want to say something like that to map out content as a
                        basis for improving access and ensuring complete content coverage?

                        Peter talked about refactoring the content and the workflow, and he
                        rightly noted that this does does not depend on structured markup per
                        se. However, he stumbled when he claimed that your chanced of getting
                        trapped with XML is less than with proprietary storage formats. But
                        how can he say that! FrameMaker has reliably supported their model
                        for nearly 20 years now with millions of documents to attest to its
                        stability whereas XML is relatively new and has produced no where
                        near the body of documents (and, I'll note, a good part of these are
                        in the FrameMaker proprietary storage format). It's premature to make
                        such claims especially with next to no proof.

                        Yes, that's right! Regardless of XML being the latest rage in academic
                        technical writing departments, NO ONE is doing credible research on
                        these issues. That leaves the field open to vendors with vested
                        interest in promoting XML. That's not to say that their claims aren't
                        right within specific situations; we just can't tell how encompassing
                        these claims can be and remain valid.

                        Barry and Dennis both commented on writers and the profession. Barry
                        suggested that jobs are under pressure and may be more threatened
                        than XML. This suggests the motivation of many writers to chase
                        technology without fully appreciating it simply to stay ahead of the
                        relevance curve. The irony of this is there are scenarios where less
                        staff is needed, replaced with greater efficiency and lower cost,
                        "egoless" topic writers. XML advocates may be increasing pressure on
                        their jobs and profession. The response of the rank and file is
                        predictable - torn between getting XML on their resume and a
                        reluctance to fully embrace change that could result in the loss of
                        their job.

                        Barry suggested that "text people are just undisciplined," and
                        that seems to characterize the profession. Taking links for example.
                        Goto "software links" was one of the seminal debates in software
                        engineering and it concluded that they are bad but 30 years later
                        there's been no similar examination of links in technical writing.
                        What are the academics and leaders of the profession doing?

                        Certainly, a better editor isn't going to resolve these and other
                        critical issues in the challenge of XML. At some point, they need
                        to be addressed head on if the potential of XML and what it represents
                        is to be realized.

                        Tim
                      • Larry Kollar
                        I ve been chewing on the responses, not finding much new to contribute to the discussion, but I wanted to throw in two cents to something Tim ... Would the
                        Message 11 of 29 , Feb 1, 2005
                        • 0 Attachment
                          I've been chewing on the responses, not finding much new to contribute
                          to the discussion, but I wanted to throw in two cents to something Tim
                          said:

                          > The same is true of the prevailing view of "meta data" as paragraphs
                          > and inline markers for "code" and a few types based on purpose
                          > (reference, instructions, concept). No where to be seen is thinking
                          > about language that describes the content of a product. For example,
                          > how do I say the following in DocBook?
                          >
                          > SOFTWARE > API > DATABASE > CONNECTION
                          >
                          > Wouldn't I want to say something like that to map out content as a
                          > basis for improving access and ensuring complete content coverage?

                          Would the "role" attribute be suitable here?

                          Tim, chime in here if I get off-track, but I think you want to make
                          explicit things that have been implicit since the beginning of
                          technical documentation. In a printed manual, your example would
                          have likely appeared in a "XYZ Software Application Programmer's
                          Reference" manual, under a chapter titled "Database Access Functions."
                          The very location of the topic in question, the book and chapter that
                          it appears in, is the metadata that describes its content. This
                          shared context between writer and reader is an assumption that's so
                          well-internalized that I've never really thought of it consciously
                          until you brought it up. Ken said earlier, "writers don't always
                          (ever?) think hierarchically," but we do. We just don't realize it.

                          Moving away from books into a web of linked topics, the implied meta-
                          data becomes more tenuous. Without the shared context of topics
                          organized into book, chapter, and section, the reader can become
                          deprived of shared context although the writer may still organize
                          topics into a hierarchical structure like XYZ/API/Database and not
                          realize that the reader no longer has access to the structure.
                          Computers, which have trouble with implied anything to begin with,
                          end up completely at sea. (You can see this any time you do a Google
                          search using keywords that have more than one meaning.)


                          There *have* been forays into resolving the problem, trying to turn
                          the implicit into the explicit -- breadcrumb trails, for example.
                          http://www.webdesignpractices.com/navigation/breadcrumb.html was
                          near the top of a Google for "web bread crumb" and describes the
                          concept pretty well. So the example topic might have a string like
                          "XYZ | Software API | Database" at the top & bottom of the page,
                          with links to hop back to the appropriate heading page.

                          Another common navigation aid is the multi-pane/frame "help" style,
                          displaying an outline of the documentation, usually highlighting
                          the topic on the screen in some way. Some readers at least may find
                          this type of aid more comfortable, because it restores that implied
                          metadata -- the entire family tree, and the topic's place in that
                          family, is quickly recognized. OmniHelp is an open-source version
                          of this concept; see http://www.omsys.com/dcl/omnihelp.htm for
                          details.

                          So there *is* some research being done, mainly ad hoc, different
                          people trying different things. I think some of Chomsky's work may
                          have touched on what I'm calling "shared context"; I just wish his
                          work was a bit more approachable.


                          So we're trying to deal with that groove/rut we've created, as
                          Barry said, over the last 600 years or so. We organize topics into
                          a hierarchy, often sub-consciously, and it's only been in the last
                          30 years or so (since SGML first appeared) that we've made any
                          attempt to formally codify how we do what we already know how to
                          do. This line of thinking leads to another fine rant:

                          How much formal structure do we really need?

                          One thing I griped about in my original rant was the complexity
                          of many of the popular DTDs. I described HTML as "a people's
                          DTD," and it is -- you can fit a quick reference to HTML's
                          structure and the most common tags on a single sheet of paper
                          without making the type very small at all. Anyone with a little
                          motivation can memorize enough HTML syntax to be conversant in
                          a few hours. Many people disparage HTML as *too* simple -- but
                          is it really?

                          In the shared context of a printed manual, a reader sees italic
                          text and can quickly determine whether it's a term, the name of
                          another manual, or something the writer deemed important enough
                          to call attention to. Even simple old HTML4 can explicitly
                          distinguish between them using dfn, cite, and em, respectively.
                          If we're writing for humans, and I think primarily we still are,
                          we could just use the <i>i tag</i> for all three and know they
                          will sort it out without even thinking about it. If we restore
                          the shared context, whether through a multi-pane help system,
                          breadcrumbs, or some other method, readers will be happy.

                          If we're writing primarily for humans, but want computers to
                          catch on, we have to be a little more explicit. For example, if
                          we're using breadcrumbs to provide shared context, we could
                          wrap the string in a "breadcrumb" tag or whatever we want to
                          call it, just to tell processing scripts what to look for. HTML
                          has a META tag that could be used to provide similar information
                          behind the scenes (i.e. not visible to the reader without using
                          "View Source"). Example:

                          [meta name="context" content="XYZ|API|Database" /]

                          If needed, the div and span tags, in conjunction with the
                          "class" attribute, could also be used to provide metadata at the
                          intra-page level.

                          Writers already know how to write, and resent authoring tools
                          that get in the way of writing (witness the gripes up-thread
                          about XML editors that don't allow structure violations). If
                          we keep in mind the implied context that our human readers
                          expect, while providing sufficient metadata for the computer
                          readers, then plain HTML (maybe with some minimal extensions)
                          might be all we *really* need. Bang out topics in whatever
                          tool you like, use HTML Tidy to turn it into valid XHTML, add
                          metadata, and go.

                          Complexity has gotten us nowhere. Let's try simplicity.

                          --
                          Larry Kollar, Senior Technical Writer, ARRIS
                          "Content creators are the engine that drives
                          value in the information life cycle."
                          -- Barry Schaeffer, on XML-Doc

                          "Ambot Sakoy" <binisiya@...> wrote on 01/28/2005 12:22:43 PM:

                          >
                          >
                          > Peter Ring and Denis Bradford both noted that the open source
                          > community surrounding XML is what is different than SGML (let's
                          > include the Frame document object model too). I was around in the
                          > 1980s and there was a community then who also responded to the
                          > potential of markup languages although there wasn't the open
                          > landscape that the web afforded XML.
                          >
                          > SGML became "captured" by big, deep pocket interests - Barry noticed
                          > signs of this happening at XML conventions. An open community is no
                          > guarentee of that not happening with XML if it fails to result in
                          > solutions that directly address the primary charter of technical
                          > documentation shops - quick, on demand, spot on information through
                          > good writing and appropriate technology at stable to reduced cost.
                          >
                          > XML/SGML is relevant only as far as it helps fulfill the entire
                          > charter.
                          > Currently, except for a few large scale, specialized situations, there
                          > is scant evidence that it does, especially in small shop settings that
                          > characterize more technical writing organizations.
                          >
                          > On reason is that technological change rarely succeeds without
                          > organizational changes, and the sophistication of most technial
                          > writing managers is inadequate even for current methods. Inventory
                          > mangement, for example, is crude and light years away from the
                          > management of topics.
                          >
                          > The same is true of the prevailing view of "meta data" as paragraphs
                          > and inline markers for "code" and a few types based on purpose
                          > (reference, instructions, concept). No where to be seen is thinking
                          > about language that describes the content of a product. For example,
                          > how do I say the following in DocBook?
                          >
                          > SOFTWARE > API > DATABASE > CONNECTION
                          >
                          > Wouldn't I want to say something like that to map out content as a
                          > basis for improving access and ensuring complete content coverage?
                          >
                          > Peter talked about refactoring the content and the workflow, and he
                          > rightly noted that this does does not depend on structured markup per
                          > se. However, he stumbled when he claimed that your chanced of getting
                          > trapped with XML is less than with proprietary storage formats. But
                          > how can he say that! FrameMaker has reliably supported their model
                          > for nearly 20 years now with millions of documents to attest to its
                          > stability whereas XML is relatively new and has produced no where
                          > near the body of documents (and, I'll note, a good part of these are
                          > in the FrameMaker proprietary storage format). It's premature to make
                          > such claims especially with next to no proof.
                          >
                          > Yes, that's right! Regardless of XML being the latest rage in academic
                          > technical writing departments, NO ONE is doing credible research on
                          > these issues. That leaves the field open to vendors with vested
                          > interest in promoting XML. That's not to say that their claims aren't
                          > right within specific situations; we just can't tell how encompassing
                          > these claims can be and remain valid.
                          >
                          > Barry and Dennis both commented on writers and the profession. Barry
                          > suggested that jobs are under pressure and may be more threatened
                          > than XML. This suggests the motivation of many writers to chase
                          > technology without fully appreciating it simply to stay ahead of the
                          > relevance curve. The irony of this is there are scenarios where less
                          > staff is needed, replaced with greater efficiency and lower cost,
                          > "egoless" topic writers. XML advocates may be increasing pressure on
                          > their jobs and profession. The response of the rank and file is
                          > predictable - torn between getting XML on their resume and a
                          > reluctance to fully embrace change that could result in the loss of
                          > their job.
                          >
                          > Barry suggested that "text people are just undisciplined," and
                          > that seems to characterize the profession. Taking links for example.
                          > Goto "software links" was one of the seminal debates in software
                          > engineering and it concluded that they are bad but 30 years later
                          > there's been no similar examination of links in technical writing.
                          > What are the academics and leaders of the profession doing?
                          >
                          > Certainly, a better editor isn't going to resolve these and other
                          > critical issues in the challenge of XML. At some point, they need
                          > to be addressed head on if the potential of XML and what it represents
                          > is to be realized.
                          >
                          > Tim
                          >
                          >
                          >
                          >
                          >
                          >
                          > Yahoo! Groups Links
                          >
                          >
                          >
                          >
                          >
                          >
                          >
                        • axialinfo
                          A slight expansion of your comment on search context, Larry: The Vivisimo search engine is an interesting antidote to the flat Google search:
                          Message 12 of 29 , Feb 1, 2005
                          • 0 Attachment
                            A slight expansion of your comment on search context, Larry:

                            The Vivisimo search engine is an interesting antidote to the "flat"
                            Google search:

                            http://www.vivismo.com

                            The FAQ has some background on the benefits of clustered searches:

                            http://vivisimo.com/html/faq

                            Sheila


                            --- In xml-doc@yahoogroups.com, Larry Kollar <larry.kollar@a...> wrote:

                            > Moving away from books into a web of linked topics, the implied meta-
                            > data becomes more tenuous. Without the shared context of topics
                            > organized into ... (You can see this any time you do a Google
                            > search using keywords that have more than one meaning.)
                          • Jim Gabriel
                            Well, having watched this one go round the houses, I finally decided to dive in and deposit $0.02. I advocate designing semantically rich schemas. Going for
                            Message 13 of 29 , Feb 1, 2005
                            • 0 Attachment
                              Well, having watched this one go round the houses, I finally decided to dive
                              in and deposit $0.02. I advocate designing semantically rich schemas. Going
                              for documentation-specific schemas adds IMHO little value to the information
                              and serves only to annoy authors who are saddled with all the extra nonsense
                              of markup languages compared to a rich DTP environment. At least with
                              semantically rich schemas, the potential long term value-add and flexibility
                              offer huge benefits over a traditional system.

                              I was responsible for designing an SGML-based publishing system in the late
                              90s for a very large, complex set of technical documentation and training
                              materials. We bought Astoria for the content management part, used
                              FrameMaker+SGML for the authoring part and designed all our own schemas
                              (SGML DTDs) to describe the content we were capturing in the content
                              management system. The schemas all described bite-sized, atomic units of
                              information that could be used in any valid context.

                              We examined DocBook and quickly dismissed it as it didn't describe our
                              content in any useful way. We already had an extremely sophisticated set of
                              FrameMaker templates that achieved everything we could have achieved through
                              DocBook, so reengineering it all over again in SGML and Omnimark seemed like
                              an enormous waste of time and money. Instead, tasked with the goal of never
                              publishing a broken link and being able to infinitely repurpose all our
                              content across any delivery platform both now and in any future (as yet
                              undesigned) document structure, we performed an information mapping exercise
                              that resulted in 50+ DTDs which we could knit together via a HyTime-based
                              Link Manager system which Chrystal Software kindly built for us to spec. The
                              end result comprised 65 DTDs, when you count the various publication DTDs
                              that we built for things like Trainers' Manuals to accompany course
                              material, Installation Guides, and so on.

                              The online published results were great -- navigation bars showed where
                              you'd been, menu bars showed the context you found yourself in, and
                              therefore where you could also go, See Also links enriched every page, all
                              terms had a glossary and a concept topic to back them up, every syntactical
                              explanation linked to an example, etc. etc. It was a constantly moving
                              kaleidoscope of richly interlinked information, similar in concept to the
                              promise of topic maps and the semantic web. Users generally loved it. The
                              people who had the biggest problem with it were the authors, who hated using
                              the software to get the stuff written. (Course developers even went on
                              strike and insisted on reverting to handing in copy in regular FrameMaker,
                              for a publishing assistant to transcribe in SGML.) Technology back then
                              really wasn't up to the task, either on the hardware or the software front.

                              As an architect, I conclude this:
                              - For design flexibility, it was fantastic.
                              - For maintainability, it was awful.
                              - The technology has moved on apace, however, and I think that it would now
                              be a much easier project all round.
                              - If you design your own schemas, you don't have any discussion groups or
                              industry specialists to go to for advice and tips.

                              For those who are interested, you can read all about this at
                              http://www.idealliance.org/papers/dx_xmle04/papers/03-02-04/03-02-04.pdf.

                              Tasked with moving to XML now, I would definitely choose semantically rich
                              schemas over documentation-specific schemas any day of the week. The pro's
                              far outweigh the con's.

                              Forgive me please if I appear to be treading on anybody's toes here.


                              Jim Gabriel




                              > -----Original Message-----
                              > From: Larry Kollar [mailto:larry.kollar@...]
                              > Sent: 01 February 2005 17:13
                              > To: xml-doc@yahoogroups.com
                              > Subject: Re: [xml-doc] Re: Rant: Is XML for documentation
                              > going the way of SGML? (long)
                              >
                              >
                              > I've been chewing on the responses, not finding much new to contribute
                              > to the discussion, but I wanted to throw in two cents to something Tim
                              > said:
                              >
                              > > The same is true of the prevailing view of "meta data" as paragraphs
                              > > and inline markers for "code" and a few types based on purpose
                              > > (reference, instructions, concept). No where to be seen is thinking
                              > > about language that describes the content of a product. For example,
                              > > how do I say the following in DocBook?
                              > >
                              > > SOFTWARE > API > DATABASE > CONNECTION
                              > >
                              > > Wouldn't I want to say something like that to map out content as a
                              > > basis for improving access and ensuring complete content coverage?
                              >
                              > Would the "role" attribute be suitable here?
                              >
                              > Tim, chime in here if I get off-track, but I think you want to make
                              > explicit things that have been implicit since the beginning of
                              > technical documentation. In a printed manual, your example would
                              > have likely appeared in a "XYZ Software Application Programmer's
                              > Reference" manual, under a chapter titled "Database Access Functions."
                              > The very location of the topic in question, the book and chapter that
                              > it appears in, is the metadata that describes its content. This
                              > shared context between writer and reader is an assumption that's so
                              > well-internalized that I've never really thought of it consciously
                              > until you brought it up. Ken said earlier, "writers don't always
                              > (ever?) think hierarchically," but we do. We just don't realize it.
                              >
                              > Moving away from books into a web of linked topics, the implied meta-
                              > data becomes more tenuous. Without the shared context of topics
                              > organized into book, chapter, and section, the reader can become
                              > deprived of shared context although the writer may still organize
                              > topics into a hierarchical structure like XYZ/API/Database and not
                              > realize that the reader no longer has access to the structure.
                              > Computers, which have trouble with implied anything to begin with,
                              > end up completely at sea. (You can see this any time you do a Google
                              > search using keywords that have more than one meaning.)
                              >
                              >
                              > There *have* been forays into resolving the problem, trying to turn
                              > the implicit into the explicit -- breadcrumb trails, for example.
                              > http://www.webdesignpractices.com/navigation/breadcrumb.html was
                              > near the top of a Google for "web bread crumb" and describes the
                              > concept pretty well. So the example topic might have a string like
                              > "XYZ | Software API | Database" at the top & bottom of the page,
                              > with links to hop back to the appropriate heading page.
                              >
                              > Another common navigation aid is the multi-pane/frame "help" style,
                              > displaying an outline of the documentation, usually highlighting
                              > the topic on the screen in some way. Some readers at least may find
                              > this type of aid more comfortable, because it restores that implied
                              > metadata -- the entire family tree, and the topic's place in that
                              > family, is quickly recognized. OmniHelp is an open-source version
                              > of this concept; see http://www.omsys.com/dcl/omnihelp.htm for
                              > details.
                              >
                              > So there *is* some research being done, mainly ad hoc, different
                              > people trying different things. I think some of Chomsky's work may
                              > have touched on what I'm calling "shared context"; I just wish his
                              > work was a bit more approachable.
                              >
                              >
                              > So we're trying to deal with that groove/rut we've created, as
                              > Barry said, over the last 600 years or so. We organize topics into
                              > a hierarchy, often sub-consciously, and it's only been in the last
                              > 30 years or so (since SGML first appeared) that we've made any
                              > attempt to formally codify how we do what we already know how to
                              > do. This line of thinking leads to another fine rant:
                              >
                              > How much formal structure do we really need?
                              >
                              > One thing I griped about in my original rant was the complexity
                              > of many of the popular DTDs. I described HTML as "a people's
                              > DTD," and it is -- you can fit a quick reference to HTML's
                              > structure and the most common tags on a single sheet of paper
                              > without making the type very small at all. Anyone with a little
                              > motivation can memorize enough HTML syntax to be conversant in
                              > a few hours. Many people disparage HTML as *too* simple -- but
                              > is it really?
                              >
                              > In the shared context of a printed manual, a reader sees italic
                              > text and can quickly determine whether it's a term, the name of
                              > another manual, or something the writer deemed important enough
                              > to call attention to. Even simple old HTML4 can explicitly
                              > distinguish between them using dfn, cite, and em, respectively.
                              > If we're writing for humans, and I think primarily we still are,
                              > we could just use the <i>i tag</i> for all three and know they
                              > will sort it out without even thinking about it. If we restore
                              > the shared context, whether through a multi-pane help system,
                              > breadcrumbs, or some other method, readers will be happy.
                              >
                              > If we're writing primarily for humans, but want computers to
                              > catch on, we have to be a little more explicit. For example, if
                              > we're using breadcrumbs to provide shared context, we could
                              > wrap the string in a "breadcrumb" tag or whatever we want to
                              > call it, just to tell processing scripts what to look for. HTML
                              > has a META tag that could be used to provide similar information
                              > behind the scenes (i.e. not visible to the reader without using
                              > "View Source"). Example:
                              >
                              > [meta name="context" content="XYZ|API|Database" /]
                              >
                              > If needed, the div and span tags, in conjunction with the
                              > "class" attribute, could also be used to provide metadata at the
                              > intra-page level.
                              >
                              > Writers already know how to write, and resent authoring tools
                              > that get in the way of writing (witness the gripes up-thread
                              > about XML editors that don't allow structure violations). If
                              > we keep in mind the implied context that our human readers
                              > expect, while providing sufficient metadata for the computer
                              > readers, then plain HTML (maybe with some minimal extensions)
                              > might be all we *really* need. Bang out topics in whatever
                              > tool you like, use HTML Tidy to turn it into valid XHTML, add
                              > metadata, and go.
                              >
                              > Complexity has gotten us nowhere. Let's try simplicity.
                              >
                              > --
                              > Larry Kollar, Senior Technical Writer, ARRIS
                              > "Content creators are the engine that drives
                              > value in the information life cycle."
                              > -- Barry Schaeffer, on XML-Doc
                              >
                              > "Ambot Sakoy" <binisiya@...> wrote on 01/28/2005 12:22:43 PM:
                              >
                              > >
                              > >
                              > > Peter Ring and Denis Bradford both noted that the open source
                              > > community surrounding XML is what is different than SGML (let's
                              > > include the Frame document object model too). I was around in the
                              > > 1980s and there was a community then who also responded to the
                              > > potential of markup languages although there wasn't the open
                              > > landscape that the web afforded XML.
                              > >
                              > > SGML became "captured" by big, deep pocket interests - Barry noticed
                              > > signs of this happening at XML conventions. An open community is no
                              > > guarentee of that not happening with XML if it fails to result in
                              > > solutions that directly address the primary charter of technical
                              > > documentation shops - quick, on demand, spot on information through
                              > > good writing and appropriate technology at stable to reduced cost.
                              > >
                              > > XML/SGML is relevant only as far as it helps fulfill the entire
                              > > charter.
                              > > Currently, except for a few large scale, specialized
                              > situations, there
                              > > is scant evidence that it does, especially in small shop
                              > settings that
                              > > characterize more technical writing organizations.
                              > >
                              > > On reason is that technological change rarely succeeds without
                              > > organizational changes, and the sophistication of most technial
                              > > writing managers is inadequate even for current methods. Inventory
                              > > mangement, for example, is crude and light years away from the
                              > > management of topics.
                              > >
                              > > The same is true of the prevailing view of "meta data" as paragraphs
                              > > and inline markers for "code" and a few types based on purpose
                              > > (reference, instructions, concept). No where to be seen is thinking
                              > > about language that describes the content of a product. For example,
                              > > how do I say the following in DocBook?
                              > >
                              > > SOFTWARE > API > DATABASE > CONNECTION
                              > >
                              > > Wouldn't I want to say something like that to map out content as a
                              > > basis for improving access and ensuring complete content coverage?
                              > >
                              > > Peter talked about refactoring the content and the workflow, and he
                              > > rightly noted that this does does not depend on structured
                              > markup per
                              > > se. However, he stumbled when he claimed that your chanced
                              > of getting
                              > > trapped with XML is less than with proprietary storage formats. But
                              > > how can he say that! FrameMaker has reliably supported their model
                              > > for nearly 20 years now with millions of documents to attest to its
                              > > stability whereas XML is relatively new and has produced no where
                              > > near the body of documents (and, I'll note, a good part of these are
                              > > in the FrameMaker proprietary storage format). It's
                              > premature to make
                              > > such claims especially with next to no proof.
                              > >
                              > > Yes, that's right! Regardless of XML being the latest rage
                              > in academic
                              > > technical writing departments, NO ONE is doing credible research on
                              > > these issues. That leaves the field open to vendors with vested
                              > > interest in promoting XML. That's not to say that their
                              > claims aren't
                              > > right within specific situations; we just can't tell how
                              > encompassing
                              > > these claims can be and remain valid.
                              > >
                              > > Barry and Dennis both commented on writers and the profession. Barry
                              > > suggested that jobs are under pressure and may be more threatened
                              > > than XML. This suggests the motivation of many writers to chase
                              > > technology without fully appreciating it simply to stay ahead of the
                              > > relevance curve. The irony of this is there are scenarios where less
                              > > staff is needed, replaced with greater efficiency and lower cost,
                              > > "egoless" topic writers. XML advocates may be increasing pressure on
                              > > their jobs and profession. The response of the rank and file is
                              > > predictable - torn between getting XML on their resume and a
                              > > reluctance to fully embrace change that could result in the loss of
                              > > their job.
                              > >
                              > > Barry suggested that "text people are just undisciplined," and
                              > > that seems to characterize the profession. Taking links for example.
                              > > Goto "software links" was one of the seminal debates in software
                              > > engineering and it concluded that they are bad but 30 years later
                              > > there's been no similar examination of links in technical writing.
                              > > What are the academics and leaders of the profession doing?
                              > >
                              > > Certainly, a better editor isn't going to resolve these and other
                              > > critical issues in the challenge of XML. At some point, they need
                              > > to be addressed head on if the potential of XML and what it
                              > represents
                              > > is to be realized.
                              > >
                              > > Tim
                              > >
                              > >
                              > >
                              > >
                              > >
                              > >
                              > > Yahoo! Groups Links
                              > >
                              > >
                              > >
                              > >
                              > >
                              > >
                              > >
                              >
                              >
                              >
                              >
                              > Yahoo! Groups Links
                              >
                              >
                              >
                              >
                              >
                              >
                              >
                              >
                            • Ambot Sakoy
                              Larry, I think you have inadvertantly concluded that one the things that XML is good for is making technical writers think and talk explicitly about
                              Message 14 of 29 , Feb 1, 2005
                              • 0 Attachment
                                Larry,

                                I think you have inadvertantly concluded that one the things that XML
                                is "good" for is making technical writers think and talk explicitly
                                about structures, including hierarchy, they intuitively already work
                                with. This includes not only the obvious structures that make up
                                documents but the "structuring" of information to these conventions.

                                But, if we look at leading efforts, like DocBook, we can see that
                                writers haven't gotten very far. They continue to confuse meta-data -
                                data about data - with the "container" in which information is kept.
                                It is simply an instance of the general document model of Frame or
                                other established tools rendered in XML for a set of specialized
                                documents (software).

                                This gives us a langauge we can share as writers when talking about
                                containers but where is the common language for talking about content?

                                As you might say, "it's in the text, the title, the chapter heading"
                                but remember, we're talking about a "programatic conversation," and to
                                a program, such text doesn't mean much without a reference to identify
                                it against.

                                We are far from dealing with dynamic issues; migration of legacy
                                material, change and maintenance over time.

                                In the end, you call for "simplicity," and that can certainly include
                                "plain old books" in many circumstances. But, what we are struggling
                                with here is the promise of a technology that can improve the use and
                                access (fast, "right" information, on demand) of information, and even
                                offer the means for quantatively testing certain quality dimensions of
                                documentation; a trade-off of complexity for better leveraged information.

                                Such a trade-off implies a significant committment of resources and a
                                test as to whether or not the benefits are worth the cost. In many
                                situations, the calculation will prove that "plain old documents"
                                cannot be beat.

                                Even if that turns out to be the case, you might be right in that the
                                lessons of XML can reinforce the "good practices" you mentioned
                                writers already practice and even inspire better application of them;
                                concise, well cataloged libraries, with documents with good, clear,
                                consistent structure, formed appropriately to thoughtfully contain the
                                information, with various indexes to give quick, smart access to key
                                pieces of information.

                                It so happens that this is the very prerequsite that seems necessary
                                for a relatively easy, non-disruptive, low-cost, successful migration
                                to DocBook-like XML and structure. If you meet this prerequsite, then
                                you are left with the question "is it worth paying to do in XML what
                                you're already doing for "free" (relatively speaking)?"

                                > Complexity has gotten us nowhere. Let's try simplicity.

                                Or something more fundamental like "at what point are the imagined
                                benefits worth the effort and complexity, and just how will we know?"

                                Tim
                              • ogormanjjka@aol.com
                                Jim; A great example of Gabriel tooting his own horn: I like it! Your post (and this is my two cents worth) and others like it moves this whole discussion
                                Message 15 of 29 , Feb 2, 2005
                                • 0 Attachment
                                  Jim;

                                  A great example of Gabriel tooting his own horn: I like it!

                                  Your post (and this is my two cents worth) and others like it moves this
                                  whole discussion closer to the main issue: there is currently a large imbalance
                                  in current XML practice between the structure of content (the containers) and
                                  the content itself. The problem is particularly evident where you see a
                                  large, disciplined effort dedicated to managing the form of the content while
                                  relegating the meaning and relevance of the content itself (which is where I
                                  thought XML was supposed to be going) to the less rigorous domains of metadata
                                  and conditional processing.

                                  Designing and building an information architecture that intentionally
                                  focuses on semantic elements restores the balance, and in my view makes all kinds
                                  of sense when the conversation turns to things like reusing and repurposing
                                  content. It makes much more sense to speak about reuse in a semantic sense than
                                  a structural one. That is not to say that structure is not critical - it
                                  just can't be the only thing.

                                  Apologies if this appears a little disjointed I am a little rushed this
                                  morning. In the final analysis, especially when considering things like
                                  internationalization of products and services, creating a better balance between the
                                  holy trinity of user-centered information: context, container, and content
                                  might head off the slide of xml into the void.

                                  Regards.

                                  John O'



                                  [Non-text portions of this message have been removed]
                                • Buss, Jason A
                                  Testing... I ve posted twice, neither of them seem to have made it to the list... Sorry for the bother, -Jason ... From: ogormanjjka@aol.com
                                  Message 16 of 29 , Feb 2, 2005
                                  • 0 Attachment
                                    Testing...

                                    I've posted twice, neither of them seem to have made it to the list...

                                    Sorry for the bother,

                                    -Jason

                                    -----Original Message-----
                                    From: ogormanjjka@... [mailto:ogormanjjka@...]
                                    Sent: Wednesday, February 02, 2005 9:06 AM
                                    To: xml-doc@yahoogroups.com
                                    Subject: Re: [xml-doc] Re: Rant: Is XML for documentation going the way
                                    of SGML? (long)



                                    Jim;

                                    A great example of Gabriel tooting his own horn: I like it!

                                    Your post (and this is my two cents worth) and others like it moves this
                                    whole discussion closer to the main issue: there is currently a large
                                    imbalance
                                    in current XML practice between the structure of content (the containers)
                                    and
                                    the content itself. The problem is particularly evident where you see a
                                    large, disciplined effort dedicated to managing the form of the content
                                    while
                                    relegating the meaning and relevance of the content itself (which is where I

                                    thought XML was supposed to be going) to the less rigorous domains of
                                    metadata
                                    and conditional processing.

                                    Designing and building an information architecture that intentionally
                                    focuses on semantic elements restores the balance, and in my view makes all
                                    kinds
                                    of sense when the conversation turns to things like reusing and repurposing

                                    content. It makes much more sense to speak about reuse in a semantic sense
                                    than
                                    a structural one. That is not to say that structure is not critical - it
                                    just can't be the only thing.

                                    Apologies if this appears a little disjointed I am a little rushed this
                                    morning. In the final analysis, especially when considering things like
                                    internationalization of products and services, creating a better balance
                                    between the
                                    holy trinity of user-centered information: context, container, and content
                                    might head off the slide of xml into the void.

                                    Regards.

                                    John O'



                                    [Non-text portions of this message have been removed]




                                    Yahoo! Groups Links
                                  • Ambot Sakoy
                                    Thank you Jim. We need more data points like yours to better understand when it makes sense to move away from the book paradigm, what s involved, at what cost
                                    Message 17 of 29 , Feb 2, 2005
                                    • 0 Attachment
                                      Thank you Jim.

                                      We need more data points like yours to better understand when it
                                      makes sense to move away from the book paradigm, what's involved, at
                                      what cost for what benefits.

                                      Personally, I favor semantically rich schemas too but I freely admit
                                      my preference is for reasons of intellectual and technical
                                      satisfaction and is NOT the right choice in many, perhaps most,
                                      situations.

                                      Your brief overview briefly brought up some of the major drawbacks.
                                      Clearly, the project was:

                                      1. Disruptive to current work and production.
                                      2. More costly, initially and ongoing.
                                      3. Complicated to manage and maintain.

                                      And, most importantly, while "customers loved it," were they willing
                                      to pay for it as measured by increased sales and profits solely based
                                      on this change?

                                      And, what about the customers that "hated it;" what do detractors
                                      have to say about it. From your description and my own experience
                                      with such systems, getting good hardcopy is a major exercise. Also,
                                      such a system should be able to produce conventional documentation
                                      for customers that demand it but such flexibility is seldom provided
                                      for.

                                      Finally, what has happened to staffing? Are they spending more time
                                      feeding the system and less time researching and developing content?
                                      Are full time production staff now required to make sure things
                                      continue to work? What are the ramp up costs for new people,
                                      including contractors?

                                      I'm on the run now, heading for work but I look forward to reading
                                      your write-up. Again, we could use many more data points like yours.
                                      Thanks for being forthcoming.

                                      Tim
                                    • Larry Kollar
                                      ... I d guess that most writers looking at XML are looking too closely, seeing DTDs, tags, attributes, and not the wide-angle view of *how* we do what we do
                                      Message 18 of 29 , Feb 2, 2005
                                      • 0 Attachment
                                        > I think you have inadvertantly concluded that one the things that XML
                                        > is "good" for is making technical writers think and talk explicitly
                                        > about structures, including hierarchy, they intuitively already work
                                        > with. This includes not only the obvious structures that make up
                                        > documents but the "structuring" of information to these conventions.

                                        I'd guess that most writers looking at XML are looking too closely,
                                        seeing DTDs, tags, attributes, and not the wide-angle view of *how*
                                        we do what we do and where we could be doing it more effectively.
                                        Maybe this thread is starting to provide a wider angle.

                                        > But, if we look at leading efforts, like DocBook, we can see that
                                        > writers haven't gotten very far. They continue to confuse meta-data -
                                        > data about data - with the "container" in which information is kept.
                                        > It is simply an instance of the general document model of Frame or
                                        > other established tools rendered in XML for a set of specialized
                                        > documents (software).
                                        >
                                        > This gives us a langauge we can share as writers when talking about
                                        > containers but where is the common language for talking about content?

                                        You've mentioned this a couple of times, and now I'm pretty sure I
                                        understand... again, it's a matter of people focusing too closely on
                                        elements like sect, procedure, and para, rather than what those bits
                                        assembled are talking about. Right? It's like the old jokes about the
                                        human body being worth a few bucks worth of carbon and water, when
                                        the organic compounds and organs comprising those basic elements are
                                        worth much more.

                                        In this view, even the higher-level DITA constructs (topic, concept,
                                        task, reference) miss the forest for the trees. They're still con-
                                        tainers; useful ones but still missing that semantic content.

                                        Topic maps [http://www.topicmaps.org/xtm/%5d amount to an (external)
                                        catalog of semantic content. Section numbers in UNIX manpages also
                                        provide a very simple content map -- section 1 describes user-level
                                        commands, section 2 for kernel calls, section 3 for the C library
                                        API, and so on. But there are aesthetic as well as practical reasons
                                        for each topic or file to include a description of its semantic
                                        content -- adding new files doesn't mean you have to go back & update
                                        an external map; just rebuild the map using the working content.
                                        Manpages also require a .NM (name) element that contains a description
                                        of the manpage (i.e. what it's about); ideally, the description should
                                        contain keywords that programs like "makewhatis" can use to build a
                                        search index. Is there really anything new under the sun? :-)


                                        > As you might say, "it's in the text, the title, the chapter heading"
                                        > but remember, we're talking about a "programmatic conversation," and to
                                        > a program, such text doesn't mean much without a reference to identify
                                        > it against.

                                        Yes... I talked about the differing needs between human readers and
                                        computer readers. As human writers writing for (up to now) primarily
                                        human readers, we have relied on the shared context of hierarchy and
                                        organization to provide the semantic content. Now we have a second
                                        audience, computers running search programs. This new audience isn't
                                        really interested in the steps of, say, an installation procedure --
                                        they're not going to actually install a widget, after all -- but want
                                        to know that some topic *is* an installation procedure for some
                                        particular product. DocBook actually *can* contain some of this
                                        metadata as-is -- for example, a section can have a sectioninfo
                                        element with a "role" attribute and a "keywordset" element. It's easy
                                        to miss this kind of stuff in a big DTD.

                                        The hard part is remembering to add the metadata, especially in the
                                        heat of a looming deadline. My home-grown DTD has an (in the light
                                        of this discussion) incomplete set of attributes that allow one to
                                        specify a product, interface (HTTP, SNMP, console, etc), and what I
                                        call "use phase" (planning, installation, configuration, operation,
                                        administration, maintenance). I was providing (by design) hooks for
                                        searching, although I hadn't gone so far as to build a search mechanism.
                                        Not all the containers have had those metadata attributes filled in;
                                        making those attributes required instead of optional could go a long
                                        way toward fixing that problem.


                                        > Even if that turns out to be the case, you might be right in that the
                                        > lessons of XML can reinforce the "good practices" you mentioned
                                        > writers already practice and even inspire better application of them;
                                        > concise, well cataloged libraries, with documents with good, clear,
                                        > consistent structure, formed appropriately to thoughtfully contain the
                                        > information, with various indexes to give quick, smart access to key
                                        > pieces of information.
                                        >
                                        > It so happens that this is the very prerequsite that seems necessary
                                        > for a relatively easy, non-disruptive, low-cost, successful migration
                                        > to DocBook-like XML and structure. If you meet this prerequsite, then
                                        > you are left with the question "is it worth paying to do in XML what
                                        > you're already doing for "free" (relatively speaking)?"

                                        If writers (individually or in groups) are providing this type of
                                        information, I think doing it in XML *can* be worth it -- a lot
                                        of those catalogs and indexes could be built automatically and any
                                        documents missing proper metadata can be flagged for attention.


                                        > > Complexity has gotten us nowhere. Let's try simplicity.
                                        >
                                        > Or something more fundamental like "at what point are the imagined
                                        > benefits worth the effort and complexity, and just how will we know?"

                                        That one I have no answer for. Putting a price tag on *not* having
                                        documentation (or good documentation) has always been problematic.

                                        --
                                        Larry Kollar, Senior Technical Writer, ARRIS
                                        "Content creators are the engine that drives
                                        value in the information life cycle."
                                        -- Barry Schaeffer, on XML-Doc
                                      • Jim Gabriel
                                        Tim, I appreciate your reply, thanks. You re right to point out that many folks won t need such a heavyweight approach to marking up their technical
                                        Message 19 of 29 , Feb 4, 2005
                                        • 0 Attachment
                                          Tim,

                                          I appreciate your reply, thanks.

                                          You're right to point out that many folks won't need such a heavyweight
                                          approach to marking up their technical documentation. In our case, it was
                                          justified by the size of the bigger picture -- an all singing, all dancing
                                          portal for customer support, training and consultancy. This was a very early
                                          example of what we all expect now from enterprise software vendors, so the
                                          output of that system would be regarded by many support departments as
                                          essential these days.

                                          As for some customers 'hating' it (the online library), we recreated the
                                          traditional doc sets for them as well, by getting to pdf through FrameMaker.
                                          Having set up the scripts to export the correct document components and
                                          build a FM book, it was a process that essentially ran itself for free,
                                          aside from the regular editing pass.

                                          To answer your question about how the staff spent their time -- it
                                          definitely meant that a disproportionate amount of every day was spent
                                          'feeding the system', but that balanced out over time. The benefits were the
                                          ones we could apply automation to. For example, early in the project, we set
                                          ourselves the goal of creating the first online course to emerge from the
                                          system by building it from components and automating the publishing. We did
                                          this by taking the equivalent of a manual, an instructor-led course, a
                                          trainer's guide, and some reference material, and entering the source text
                                          and graphics into the system and then producing out the other end the
                                          animated online course, pdf and html. We put a team of 30 people on it -- a
                                          mixture of trainers, graphic designers, authors, course developers, editors
                                          and publishers (Omnimark experts), and a manager or two (;-) and turned it
                                          around in a week. It was rough at the edges, but a phenomenal demonstration
                                          of what repurposing content and multiple outputs are all about.

                                          I haven't worked for the company concerned for some years now, but I gather
                                          that the system has now joined the league of 'legacy' apps. A re-org
                                          distributed the staff around various other cost centers. You need a strong
                                          central team to keep this sort of thing running, so I imagine the knowledge
                                          would have evaporated. Such a team gets very expensive, and can be difficult
                                          to justify these days.

                                          Rgds,
                                          Jim

                                          > And, what about the customers that "hated it;" what do detractors
                                          > have to say about it. From your description and my own experience
                                          > with such systems, getting good hardcopy is a major exercise. Also,
                                          > such a system should be able to produce conventional documentation
                                          > for customers that demand it but such flexibility is seldom provided
                                          > for.

                                          > Finally, what has happened to staffing? Are they spending more time
                                          > feeding the system and less time researching and developing content?
                                          > Are full time production staff now required to make sure things
                                          > continue to work? What are the ramp up costs for new people,
                                          > including contractors?
                                          >
                                        • Norman Walsh
                                          / Larry Kollar was heard to say: [...] ... I m not sure how or why XSLT gets criticized (or maybe it s praise?) for being highly
                                          Message 20 of 29 , Feb 4, 2005
                                          • 0 Attachment
                                            / Larry Kollar <larry.kollar@...> was heard to say:
                                            [...]
                                            | Shortly after XML appeared came XSL, a highly complex transformation
                                            | and formatting language

                                            I'm not sure how or why XSLT gets criticized (or maybe it's praise?)
                                            for being highly complex; it has a grand total of about 35 elements.
                                            It was designed, from the beginning, to be sufficiently rich to
                                            transform documents (the stuff people write, not the stuff that gets
                                            shipped around in XML-RPC packets) for the purpose of publishing them.
                                            There's gobs and gobs of stuff that could usefully be put in a
                                            transformation language that were explicitly left out because they
                                            weren't needed for documentation formatting. There were long arguments
                                            about whether we even needed the ability to do the identity transform
                                            for goodness sake, because it wasn't clear that that was necessary for
                                            documentation.

                                            It turns out that lots of folks have used XSLT for lots more
                                            interesting and complex things than documentation, and the XSLT 2.0
                                            effort has taken a somewhat broader view of transformation than 1.0
                                            did, but it's hardly a model of intrinsic complexity.

                                            It has two fundamental aspects that force stylesheet writers to think
                                            differently than programmers in modern, procedural languages. It's
                                            expressed in XML (which some people hate but I don't know how I'd live
                                            without since I often want to transform my stylesheets) and it's a
                                            functional language which is really different from Perl, C, etc.
                                            Neither of those is intrinsicly complex, just different.

                                            | that was quickly broken into XSLT and XSL-FO components. And we have

                                            There was debate about whether those should be separate specs or not
                                            too. Eventually there were folks on the WG that wanted to do one and
                                            not the other so it was an issue of editorial simplicity as much as
                                            anything else.

                                            | XPath (another amoeba-like split of XSLT),

                                            XPath was perceived by the community as generally valuable. I think
                                            it's been a dreadful mistake in some ways (because it introduced
                                            QNames in content), I regret that I didn't see the train wreck coming
                                            and work harder to preserve the XSL submission's original model of a
                                            pattern and a rule, both expressed in XML, but that's water under the
                                            bridge now.

                                            | XSchema, XQuery, SOAP, etc. More layers, many of which are
                                            | fortunately geared toward the interchange side of things rather than
                                            | documentation.

                                            Why is it bad, in principle, that the simple ideas of XML have been
                                            used by other communities to satisfy their goals?

                                            | So what's the problem? In a word, attitude.
                                            |
                                            | The first problem is the attitude of "everything must be XML"
                                            | once again leads us down the path of ignoring perfectly workable
                                            | (and free, in most cases) technologies in favor of "solutions"
                                            | that add expense and complexity and give little or no gain in
                                            | return. Seriously, what does XSL-FO do that TeX or Groff can't?

                                            I really don't know how to answer that question. Nothing, I suppose,
                                            is one answer. Except, of course, that it's expressed in XML which
                                            makes all those general purpose tools that I've now got in my back
                                            pocket (parsers, validators, editors, transformation languages,
                                            query languages, etc., etc., etc.) immediately useful.

                                            Perhaps you would have been happy experimenting with extensions to TeX
                                            or groff by writing your own special purpose tools for parsing,
                                            validating, editing, transforming, and querying those documents (not
                                            only in English but also in every other language supported by
                                            Unicode?), but I'm just as happy not to have to.

                                            | I know for sure I can define a page layout in Groff using a lot
                                            | fewer lines of code than I could in FO.

                                            Really? Are you sure? And could you write the tool that allows you to
                                            manipulate that code to change the presentation and layout just as
                                            easily? I admit there's a certain unfortunate "bare minimum" of
                                            boilerplate required in an XSL-FO document, but it seemed necessary at
                                            the time in order to support the possibility of richer page models in
                                            the future and fully internationalized printing.

                                            | may be. If we wait for the vendors to give us *their* solution,
                                            | we'll be right back to the days of six-figure implementation
                                            | and five-figure support costs -- and XML (as a documentation
                                            | tool) will become "eXcellent, Maybe Later" and join SGML in
                                            | obscurity.

                                            I dunno, I've built an entire XML publishing system around a
                                            reasonable schema (free), a good editor (free), and a reasonable set
                                            of stylesheets (free). Getting to the web is free, getting to print
                                            isn't free yet, but I'm hoping it will become free eventually.

                                            | It doesn't have to be that way. Not only is XML just as open
                                            | (if not more so) than SGML, a plethora of Free, Open Source,
                                            | and low-cost commercial tools have grown up around it or have
                                            | been adapted to work with it. The pieces are lying all around
                                            | us, like several model car kits all jumbled together. We need
                                            | to start picking up pieces, fit them together, and start applying
                                            | glue and paint.

                                            Absolutely!

                                            | Needless to say, this is my personal opinion and not necessarily
                                            | that of my employer.

                                            Mine too.

                                            There's no question that the family of XML specifications has gotten
                                            as complicated as SGML, perhaps more so. But there's nothing that says
                                            we have to use all of them.

                                            I guess I don't fundamentally disagree with the spirit of your rant,
                                            I'm just not sure I perceive the details of the situation in the same
                                            way that you do.

                                            OTOH, as a professional standards wonk, I suppose I'm part of the
                                            problem, not the solution :-)

                                            Be seeing you,
                                            norm

                                            --
                                            Norman Walsh <normyahoo@...> | A man can believe a considerable
                                            http://nwalsh.com/ | deal of rubbish, and yet go about
                                            | his daily work in a rational and
                                            | cheerful manner.--Norman Douglas


                                            [Non-text portions of this message have been removed]
                                          • Larry Kollar
                                            ... gather ... strong ... knowledge ... difficult ... That s a great illustration of *how* complex structured documentation systems aren t working,
                                            Message 21 of 29 , Feb 7, 2005
                                            • 0 Attachment
                                              Jim Gabriel wrote:

                                              > I haven't worked for the company concerned for some years now, but I
                                              gather
                                              > that the system has now joined the league of 'legacy' apps. A re-org
                                              > distributed the staff around various other cost centers. You need a
                                              strong
                                              > central team to keep this sort of thing running, so I imagine the
                                              knowledge
                                              > would have evaporated. Such a team gets very expensive, and can be
                                              difficult
                                              > to justify these days.

                                              That's a great illustration of *how* complex structured documentation
                                              systems aren't working, unfortunately. If the whole shebang breaks
                                              down at the first re-org, it's (IMO, of course) too fragile to deploy.

                                              I'm afraid large documentation departments are a thing of the past
                                              for most industries, as far as I can tell. In these dark days of
                                              tiny departments and nearly nonexistent budgets, a simplified
                                              approach to XML and structured documentation is the only way I can
                                              see for it to reach widespread acceptance.

                                              In the long run, the need for explicit structure may become moot --
                                              eventually, computers (or rather, the software) could become smart
                                              enough to interpret the shared context we already use and extract
                                              structure and metadata for us. It's possible to extract some amount
                                              of structure already, based on formatting (see Exegenix and several
                                              other programs, commercial to Free). But human intervention is still
                                              required at this stage -- for example, to interpret the meaning (or
                                              role) of italic strings -- and metadata isn't on the radar yet.

                                              For now, it's up to us to feed the system, maintain it, and still
                                              find the time to actually *write* something on occasion. A system
                                              that's easy to set up & maintain is the only thing that's going to
                                              work for small groups or lone writers.

                                              --
                                              Larry Kollar, Senior Technical Writer, ARRIS
                                              "Content creators are the engine that drives
                                              value in the information life cycle."
                                              -- Barry Schaeffer, on XML-Doc
                                            • Ambot Sakoy
                                              Right on Larry. It s fairly typical in the software industry to have techncial writers directly associated with engineering groups where they can get a certain
                                              Message 22 of 29 , Feb 7, 2005
                                              • 0 Attachment
                                                Right on Larry.

                                                It's fairly typical in the software industry to have techncial writers
                                                directly associated with engineering groups where they can get a
                                                certain amount of cover (cut Documentation but not the engineering
                                                team) but are constrained by the things you and Jim mentioned and
                                                others as well.

                                                This does NOT mean that XML is beyond reach or, if adopted in some
                                                form, is a cost and management landmine. We just have to start facing
                                                facts - actually, start raising them over the din of enthusiastic hype
                                                - and begin to understand the implications and true costs of XML
                                                solutions. As it turns out, the surrounding issues are actually more
                                                challenging and critical than the technology. They include:

                                                1. Sustaining staffing and management.
                                                2. Hardening systems against reorganization and project/product
                                                changes.
                                                3. Scalibility and ongoing extensibility (new/changing applications).
                                                4. Legacy convervsion.
                                                5. Retreat - how do I get back, if the "solution" fails?
                                                6. Economic/business justification.
                                                7. Maintaining tools and source over time.
                                                8. Inventory management.
                                                9. Training, work complexity, production complexity and other
                                                demands on staffing and productivity.

                                                As for the technology, Norman said it for me. There is nothing to
                                                debate or be confused about; the tools are just too damn useful to not
                                                take up, and not just for documenation. But then I came into
                                                documentation from software engineering. I'm a "writer" who continues
                                                to think "technology, tools and process" before I think "paper and
                                                pencil."

                                                Tim


                                                --- In xml-doc@yahoogroups.com, Larry Kollar <larry.kollar@a...> wrote:
                                                > Jim Gabriel wrote:
                                                >
                                                > > I haven't worked for the company concerned for some years now, but I
                                                > gather
                                                > > that the system has now joined the league of 'legacy' apps. A re-org
                                                > > distributed the staff around various other cost centers. You need a
                                                > strong
                                                > > central team to keep this sort of thing running, so I imagine the
                                                > knowledge
                                                > > would have evaporated. Such a team gets very expensive, and can be
                                                > difficult
                                                > > to justify these days.
                                                >
                                                > That's a great illustration of *how* complex structured documentation
                                                > systems aren't working, unfortunately. If the whole shebang breaks
                                                > down at the first re-org, it's (IMO, of course) too fragile to deploy.
                                                >
                                                > I'm afraid large documentation departments are a thing of the past
                                                > for most industries, as far as I can tell. In these dark days of
                                                > tiny departments and nearly nonexistent budgets, a simplified
                                                > approach to XML and structured documentation is the only way I can
                                                > see for it to reach widespread acceptance.
                                                >
                                                > In the long run, the need for explicit structure may become moot --
                                                > eventually, computers (or rather, the software) could become smart
                                                > enough to interpret the shared context we already use and extract
                                                > structure and metadata for us. It's possible to extract some amount
                                                > of structure already, based on formatting (see Exegenix and several
                                                > other programs, commercial to Free). But human intervention is still
                                                > required at this stage -- for example, to interpret the meaning (or
                                                > role) of italic strings -- and metadata isn't on the radar yet.
                                                >
                                                > For now, it's up to us to feed the system, maintain it, and still
                                                > find the time to actually *write* something on occasion. A system
                                                > that's easy to set up & maintain is the only thing that's going to
                                                > work for small groups or lone writers.
                                              • melanie.kendell
                                                Hi All I have been watching this thread with great interest and I think it s time I chimed in. ... This is exactly what I m doing at the moment. I agree it has
                                                Message 23 of 29 , Feb 7, 2005
                                                • 0 Attachment
                                                  Hi All

                                                  I have been watching this thread with great interest and I think it's time I chimed in.

                                                  Larry Kollar wrote:
                                                  > I'm afraid large documentation departments are a thing of the past
                                                  > for most industries, as far as I can tell. In these dark days of
                                                  > tiny departments and nearly nonexistent budgets, a simplified
                                                  > approach to XML and structured documentation is the only way I can
                                                  > see for it to reach widespread acceptance.

                                                  This is exactly what I'm doing at the moment. I agree it has to be simple to have any chance of success. The other thing that is the stumbling block for most documentation departments (or sole writers) is that you can't take your documents out of circulation for six months while you sort out the whole toolchain.

                                                  To this end, we are using FrameMaker 7.1 as our way in to XML. This gives us many advantages:

                                                  * we can publish at any stage - unstructured, structured, and finally, round-tripping to XML

                                                  * we can polish the print publication before final printing - pagination, tweaking graphic sizes, etc

                                                  * we can use standard single-sourcing tools such as WebWorks or RoboHelp to create online help, html, etc

                                                  * our writers are familiar with this type of editor (even Word users quickly come up to speed), there are some differences with how they work in structured FrameMaker but they are not having to learn a whole new paradigm

                                                  * we don't have to include the whole book in the structure

                                                  To cover the last point in more detail, writing a DTD that caters for all the corner cases of front and back matter is not always necessary. The document I am currently working on is a catalogue where the guts of the document - the products - are regular in structure and are going to be single-sourced with a web publication where the presentation of the information is going to be quite different. Ideal XML fodder.

                                                  The front and back matter, on the other hand, is only for use in the printed catalogue and contains marketing and graphic designer fluff, and tables generated from the product information. Very unsuited to XML.

                                                  Using FrameMaker I can create a book that contains unstructured and structured chapters and only round-trip the structured chapters into my CMS so that the website can access them.

                                                  We have got to the structured stage and this is working even though my authors are half-way round the world and hadn't even used Word styles before - so it ***had*** to be simple.

                                                  FrameMaker is by no means the perfect tool and has been poorly supported by Adobe for years, but it seems to be the best answer to making XML accessible to the people it was originally designed for - documentation rather than data transfer. Don't get me wrong I am happy that the data transfer people have embraced XML precisely because it gives it traction, but it does mean that there are conflicting agendas out there.

                                                  For example, one feature request mentioned before in this thread was the ability to have invalid structure at certain stages. This is something a data transfer person would probably not have a use for, but as a writer I immediately agreed that this was very important. The perfect example of this is cut and paste - valid structure in one spot, invalid in the new placement - I don't want to be prevented from moving text simply because the structure will be temporarily invalid.

                                                  The way FrameMaker handles this is that you can move stuff where you want but the invalid structure is shown in red in the Structure View and if you try to export it to XML it will report the error and fail.

                                                  Alternatively, if you are creating a new element you would normally be offered only valid elements, but you can change a setting to allow you to access all possible elements if you need to break the structure temporarily (eg if you want to create structure valid for the new placement before you move it - different people work in different ways).

                                                  "What about propriatary lock-in?" I hear you say - after all that's one of the tenets of using a standard such as XML. This is not high on my priority list right now, but it is comforting to know that once my structured chapters are safely round-tripping through my CMS in XML I can use any XML editor and if I want to publish directly from the XML I can learn XSL-FO or whatever - but there's no rush.

                                                  As for my front and back matter, there's not enough content in those chapters to cause a drama even if Adobe fell into a black hole and all copies of FrameMaker installed around the world exploded immediately.

                                                  I hope this has given some of you an insight into how XML is being used in the real world, for real documentation, right now.

                                                  Thanks for listening.
                                                  -Melanie Kendell
                                                • Larry Kollar
                                                  ... That s pretty much the current setup I m using, except I m using 7.0 (because Adobe in their nonexistent wisdom dropped MacOS development). Like you, I
                                                  Message 24 of 29 , Feb 8, 2005
                                                  • 0 Attachment
                                                    > To this end, we are using FrameMaker 7.1 as our way in to XML. This
                                                    > gives us many advantages [...]
                                                    >
                                                    > writing a DTD that caters
                                                    > for all the corner cases of front and back matter is not always
                                                    > necessary.

                                                    That's pretty much the current setup I'm using, except I'm using 7.0
                                                    (because Adobe in their nonexistent wisdom dropped MacOS development).
                                                    Like you, I don't try to structure boilerplate stuff like front and
                                                    back pages.

                                                    Still, setting up Frame for structured writing is nontrivial. The
                                                    EDD is a beast and can get out of hand pretty quickly if (like me)
                                                    you don't know what you're doing at first. I've recommended to others
                                                    looking at using Frame this way that they mentally prepare to throw
                                                    out their first efforts and start over. There are benefits to the way
                                                    Frame does things -- you can't make changes to a DTD and forget to
                                                    fix the stylesheet, for example. Being able to break structure is
                                                    another advantage; one item in my bag of tricks transforms OPML
                                                    (an XML outliner DTD) to my home-grown DTD, missing a couple of
                                                    required elements but enough to capture the outline properly. Open
                                                    Structure View, look for red marks, fill in elements. It's not quite
                                                    as nice as having a built-in outliner, but it does the job.

                                                    Some of the later talk in this thread discusses the importance of
                                                    metadata, "feeding the system" as it were. What kind of metadata
                                                    has your department found useful, and how much effort does it take
                                                    to properly maintain it?

                                                    --
                                                    Larry Kollar, Senior Technical Writer, ARRIS
                                                    "Content creators are the engine that drives
                                                    value in the information life cycle."
                                                    -- Barry Schaeffer, on XML-Doc
                                                  • melanie.kendell
                                                    Hi Larry et al ... I would agree 100% with you there! To me, getting the structure right is ***the*** most critical aspect of the whole exercise and it s
                                                    Message 25 of 29 , Feb 8, 2005
                                                    • 0 Attachment
                                                      Hi Larry et al

                                                      > Setting up Frame for structured writing is nontrivial. The
                                                      > EDD is a beast and can get out of hand pretty quickly if (like me)
                                                      > you don't know what you're doing at first. I've recommended to others
                                                      > looking at using Frame this way that they mentally prepare to throw
                                                      > out their first efforts and start over.

                                                      I would agree 100% with you there! To me, getting the structure right is ***the*** most critical aspect of the whole exercise and it's unlikely that you'll get it right first time unless you've been through the hoops quite a few times (and there aren't many people that have done that yet).

                                                      > There are benefits to the way
                                                      > Frame does things -- you can't make changes to a DTD and forget to
                                                      > fix the stylesheet, for example.

                                                      The way I tackle the whole process (maybe because my background is technical writing rather than programming and I find working from the text easier) is:

                                                      1. Work out the stylesheet on a real example of the text
                                                      It doesn't matter if the font isn't exactly the shade of sky-blue-pink you wanted but the styles will automatically help you think about the structure even if it is only from a terminal leaf point of view.

                                                      2. Start working out an EDD to give hierarchy to the elements
                                                      You've got to concentrate on EDD *or* DTD not both. Personally I prefer EDD 'cos I can work directly with the real text and immediately see problems with the structure - mainly by seeing red bits in the structure, but also through how the text looks. People that disparage WYSIWYG editors for XML don't give credit that some people *can* distinguish between a problem with a style and a problem with the structure, and miss out on the fact that WYSIWYG can help to alert you to problems with structure.

                                                      3. Work out the attributes you will need, mainly for manipulation of content for publications
                                                      For my project, even though the website is some way off yet, the most important consideration for attributes was what search criteria would be useful to website visitors.

                                                      4. Once the EDD is starting to take shape, use the conversion table to fine tune it
                                                      FrameMaker has a really useful feature where you can generate a table for converting unstructured to structured Frame. This automatically lists all the styles used and suggests elements. You then edit the table to reflect the real elements, build hierarchical rules (basically the same rules as in the EDD) that allow you to wrap elements together under a parent element iteratively, populate default attributes, etc. This helps you test your emerging EDD 'cos if the rules don't work in conversion they probably aren't quite right.

                                                      5. Once you've tested your conversion six or seven thousand times, do the conversion for real
                                                      You only want to do this once your EDD is looking pretty solid as it can be harder to change things after this point depending on the volume of text and exactly what the changes are. This is the easiest way I've found for marking up unstructured content (once the conversion table is debugged).

                                                      6. Work on the text formatting and layout side of the EDD
                                                      FrameMaker allows you to do some fairly clever but sometimes arcane stuff with conditional rules and prefixes and suffixes to generate regular text from attributes. For example, rather than have an element containing the text "Lyophilised Monoclonal" stored 1,000 times (with no guarantee that it is always correctly spelled), if the product is of ProductType m and has the CodePrefix NCL-, the text "Lyophilised Monoclonal (NCL-" is automatically generated before the content of the ProductCode element. You may find during this process that you have to change some of your initial ideas on structure (particularly to do with attributes).

                                                      7. When the EDD is perfect (until someone asks for the next change), export to DTD
                                                      This is where I am at now and, while I can get an error free export for the DTD, I'm having a few headaches applying the resulting DTD to the XML export of the chapters. I'm sure (like the problems I had at earlier stages) that once I know what I'm doing it will all fall into place. And that once it works it will be robust.

                                                      > Some of the later talk in this thread discusses the importance of
                                                      > metadata, "feeding the system" as it were. What kind of metadata
                                                      > has your department found useful, and how much effort does it take
                                                      > to properly maintain it?

                                                      Metadata is simply data about data. This means different things to different people. A lot of people use it to mean the keywords used to promote their sites to search engines. To me, the metadata is inherent in the elements and attributes used to mark up the text - the stuff that allows me to identify and categorise the content.

                                                      Which is why having a semantic schema (note the small s) is so important. Marking up slabs of text in a generic DocBook-type schema will not generally give you adequate ROI. The schema must reflect the types of manipulation you intend to perform on the text. In general, this means creating your own schema for your own content (although DITA is looking promising, but not quite ready yet).

                                                      For example, my products have an atypical hierarchy ProductBlock>optional MultiCloneProduct>Product>Clone that wouldn't be available in any "standard". Each of these elements allows me to grab everything to do with a particular product at a specific level so I can offer all the information about a product, the details of the thing that is actually for sale, or the clones represent a product, depending on the context. Choice-type (or enumeration-type) attributes on those elements allow me to search for known values that categorise them.

                                                      In effect, we don't "feed the system" we mark up the text (or more generally, use conversion to mass mark it up) to give it structure, then select attribute values according to need, and viola - metadata.

                                                      The "page furniture" of the website could well have the other sort of metadata (the keyword stuff) but the content that I'm dealing with doesn't require it.

                                                      Anyone else got some real-life examples they want to share?

                                                      -Melanie
                                                    • mike feimster
                                                      I think this thread is great! It has everyone discussing possibilities, pitfalls, and real-life work. ... My first structured Frame project was a self-paced
                                                      Message 26 of 29 , Feb 9, 2005
                                                      • 0 Attachment
                                                        I think this thread is great! It has everyone discussing possibilities,
                                                        pitfalls, and real-life work.

                                                        >Anyone else got some real-life examples they want to share?

                                                        My first structured Frame project was a self-paced tutorial. I created what
                                                        amounts to a one-time EDD with elements such as exercise, task, input,
                                                        ui-element, etc. Totally unusable for anything other than a self-paced
                                                        tutorial written the way I wrote it. <g> (It was also the first time I ever
                                                        wrote a self-paced tutorial. <vbg>

                                                        For my next structured project, I analyzed the existing docs (and took into
                                                        account other docs, future possibilities, etc.) and developed the structure
                                                        in a spreadsheet. Each element has its own tab. On the tab are the allowed
                                                        parent elements, allowed child elements, attributes, a description of the
                                                        element, and general formatting info for both PDF and HTML. The parent and
                                                        child elements are hyperlinks to their tabs.

                                                        Once I was comfortable with the structure, I created an initial DTD. I
                                                        started with the DTD because I can create a basic DTD more quickly. I
                                                        imported the DTD into an EDD file, and finished it off there. Once I had the
                                                        EDD "perfected," I generated a new DTD.

                                                        The elements are based more on the structure of the docs than pure
                                                        semantics. For example, book, chapter, section, procedure, list, figure. I
                                                        chose this route to make it easier to port the structure to other projects.
                                                        In my limited experience creating highly semantic DTDs, I have found that
                                                        they only had limited uses.

                                                        I mapped the elements to the paragraph and character styles in an existing
                                                        template. I only had to make a few changes to the template, and I probably
                                                        would have made them anyway.

                                                        Next, I created a conversion table to convert my unstructured docs to
                                                        structured. This got the docs most of the way there.

                                                        I added a couple read/write rules to handle graphics and XML linefeeds.

                                                        I created an XSLT that generates a set of HTML files for online help. In the
                                                        help, related topic links are generated dynamically based on a sections
                                                        child or sibling sections. X-refs point to the specific HTML files and the
                                                        wording is appropriate for the web, i.e., no see page 24. Full size screen
                                                        caps are treated as popups. I used the xsl:document element in Saxon to
                                                        generate multiple HTML files.

                                                        The only nod to unstructured Frame is the use of conditional text for some
                                                        of the text and for the Figures/graphics/captions. I could not figure out
                                                        how to position the caption under the graphic without putting it in the
                                                        anchored frame.

                                                        Finally, I created some batch files to test the XML and generate the help
                                                        set in case I get hit by a bus.

                                                        I am now in the process of setting up the structure for another set of apps.
                                                        I will probably get rid of the chapter elements and use the section element
                                                        with additional conditions in the EDD to differentiate between introduction,
                                                        chapter, appendix, first-level sections, and second-level sections. I will
                                                        also add some attributes to mark the nodes for specific products only and
                                                        specific media only. I plan to stop generating the HTML locally, and put the
                                                        XML on the server. I'll Java or ASP to perform the XSL processing on the
                                                        fly.

                                                        I love
                                                      • Peter Ring
                                                        For me, the most important lesson in this thread so far is that -- a bit contrary to conventional XML wisdom -- you should start with existing deliverables,
                                                        Message 27 of 29 , Feb 10, 2005
                                                        • 0 Attachment
                                                          For me, the most important lesson in this thread so far is that -- a bit contrary to conventional XML wisdom -- you should start with existing deliverables, especially for typeset stuff.

                                                          If your existing deliverables are not already well structured, they won't become so by magic, just by introducing XML into the workflow. A mess is a mess, whether XML- or Word-based. Start by cleaning up the layout and logistics of existing deliverables and source documents.

                                                          Given well structured deliverables, it is much easier to build e.g. a FrameMaker structured application or an XSL-FO stylesheet from the desired output than from abstract ideas about the deliverable. Typeset stuff is a lot more complex to reason about than most nerds and pointy-haired bosses acknowledge. To use a buzzword du jour, you need test-driven development. You know what the result should look like and how it should behave, and the development process is a step-wise refinement in which you gradually get wiser about requirements to the input format.

                                                          Of course, the structure that is optimal for typesetting probably isn't optimal for storage and re-use in other channels. So what? you don't have to use it for storage. The typeset deliverable is likely composed from a number of source documents/entities, so you need a 'compilation' step in the processing pipeline anyway. A storage-to-almost-presentation transformation step is no big deal.

                                                          kind regards
                                                          Peter Ring


                                                          > -----Original Message-----
                                                          > From: mike feimster [mailto:mike.feimster@...]
                                                          > Sent: 9. februar 2005 14:51
                                                          > To: xml-doc@yahoogroups.com; melanie.kendell@...
                                                          > Subject: RE: [xml-doc] Re: Rant: Is XML for documentation
                                                          > going the way
                                                          > of SGML? (long)
                                                          >
                                                          >
                                                          >
                                                          > I think this thread is great! It has everyone discussing
                                                          > possibilities,
                                                          > pitfalls, and real-life work.
                                                          >
                                                          > >Anyone else got some real-life examples they want to share?
                                                          >
                                                          > My first structured Frame project was a self-paced tutorial.
                                                          > I created what
                                                          > amounts to a one-time EDD with elements such as exercise, task, input,
                                                          > ui-element, etc. Totally unusable for anything other than a self-paced
                                                          > tutorial written the way I wrote it. <g> (It was also the
                                                          > first time I ever
                                                          > wrote a self-paced tutorial. <vbg>
                                                          >
                                                          > For my next structured project, I analyzed the existing docs
                                                          > (and took into
                                                          > account other docs, future possibilities, etc.) and developed
                                                          > the structure
                                                          > in a spreadsheet. Each element has its own tab. On the tab
                                                          > are the allowed
                                                          > parent elements, allowed child elements, attributes, a
                                                          > description of the
                                                          > element, and general formatting info for both PDF and HTML.
                                                          > The parent and
                                                          > child elements are hyperlinks to their tabs.
                                                          >
                                                          <snip/>
                                                        • Ambot Sakoy
                                                          Not only the relative structure of your source documents but the other dimensions as well. 1. Inventory management What makes you think you can deal with a
                                                          Message 28 of 29 , Feb 10, 2005
                                                          • 0 Attachment
                                                            Not only the relative structure of your source documents but the other
                                                            dimensions as well.

                                                            1. Inventory management
                                                            What makes you think you can deal with a myriad of "topics,"
                                                            "chunks" or what ever you're in the habit of calling labelled
                                                            content when you don't know what all your product document
                                                            deliverables are much less where all source files are stored
                                                            and secured?

                                                            2. Project management
                                                            If tools and people are hard to manage for a relatively few,
                                                            basically handcrafted books using a well travelled path carved
                                                            out over the past 20-30 years, what makes you believe things
                                                            will be easier switching to a new technology with unstable
                                                            point tools produced and promoted by "come and go" vendors
                                                            and "free" sources plus other challenges in a field with
                                                            little wisdom and guidence forged from long experience?

                                                            3. Maintenance, change and extensibility
                                                            In the enthusiasm to embrace a promised panacea technology,
                                                            it is easy to think that everything will remain the same.
                                                            If you find these concerns difficult and challenging, they
                                                            will become even more so with more sophisticated technology,
                                                            changing consumer demands and staff turn over.

                                                            Don't overlook the fact that technology adoption and change comes with
                                                            upfront and periodic sunk costs as well as ongoing expense. Like any
                                                            investment, do due diligence. Is the expense really worth the actual
                                                            (not potential) required benefits? In many cases, it will NOT. If you
                                                            don't know or insist on going ahead despite unfavorable analysis,
                                                            you'd better have a good exit strategy in place and don't burn any
                                                            bridges behind you; know how you'll extract yourself before you commit.

                                                            I'm speaking mostly for typical documentation shops which tend to be
                                                            small and far from lavishly funded, and for "clear as bell" situations
                                                            where data is already understood to be naturally well structured and
                                                            process automation is the only feasible solution. Bill Hall previously
                                                            gave an excellent description of such a situation. See post 3582 and
                                                            others related to it.

                                                            Tim


                                                            --- In xml-doc@yahoogroups.com, "Peter Ring" <pri@m...> wrote:
                                                            > For me, the most important lesson in this thread so far is that -- a
                                                            bit contrary to conventional XML wisdom -- you should start with
                                                            existing deliverables, especially for typeset stuff.
                                                            >
                                                            > If your existing deliverables are not already well structured, they
                                                            won't become so by magic, just by introducing XML into the workflow. A
                                                            mess is a mess, whether XML- or Word-based. Start by cleaning up the
                                                            layout and logistics of existing deliverables and source documents.
                                                            >
                                                            > Given well structured deliverables, it is much easier to build e.g.
                                                            a FrameMaker structured application or an XSL-FO stylesheet from the
                                                            desired output than from abstract ideas about the deliverable. Typeset
                                                            stuff is a lot more complex to reason about than most nerds and
                                                            pointy-haired bosses acknowledge. To use a buzzword du jour, you need
                                                            test-driven development. You know what the result should look like and
                                                            how it should behave, and the development process is a step-wise
                                                            refinement in which you gradually get wiser about requirements to the
                                                            input format.
                                                            >
                                                            > Of course, the structure that is optimal for typesetting probably
                                                            isn't optimal for storage and re-use in other channels. So what? you
                                                            don't have to use it for storage. The typeset deliverable is likely
                                                            composed from a number of source documents/entities, so you need a
                                                            'compilation' step in the processing pipeline anyway. A
                                                            storage-to-almost-presentation transformation step is no big deal.
                                                            >
                                                            > kind regards
                                                            > Peter Ring
                                                            >
                                                            >
                                                            > > -----Original Message-----
                                                            > > From: mike feimster [mailto:mike.feimster@a...]
                                                            > > Sent: 9. februar 2005 14:51
                                                            > > To: xml-doc@yahoogroups.com; melanie.kendell@b...
                                                            > > Subject: RE: [xml-doc] Re: Rant: Is XML for documentation
                                                            > > going the way
                                                            > > of SGML? (long)
                                                            > >
                                                            > >
                                                            > >
                                                            > > I think this thread is great! It has everyone discussing
                                                            > > possibilities,
                                                            > > pitfalls, and real-life work.
                                                            > >
                                                            > > >Anyone else got some real-life examples they want to share?
                                                            > >
                                                            > > My first structured Frame project was a self-paced tutorial.
                                                            > > I created what
                                                            > > amounts to a one-time EDD with elements such as exercise, task, input,
                                                            > > ui-element, etc. Totally unusable for anything other than a self-paced
                                                            > > tutorial written the way I wrote it. <g> (It was also the
                                                            > > first time I ever
                                                            > > wrote a self-paced tutorial. <vbg>
                                                            > >
                                                            > > For my next structured project, I analyzed the existing docs
                                                            > > (and took into
                                                            > > account other docs, future possibilities, etc.) and developed
                                                            > > the structure
                                                            > > in a spreadsheet. Each element has its own tab. On the tab
                                                            > > are the allowed
                                                            > > parent elements, allowed child elements, attributes, a
                                                            > > description of the
                                                            > > element, and general formatting info for both PDF and HTML.
                                                            > > The parent and
                                                            > > child elements are hyperlinks to their tabs.
                                                            > >
                                                            > <snip/>
                                                          • Christian Roy
                                                            ... [...] Tim should be known as the Devil s Advocate -] K
                                                            Message 29 of 29 , Feb 11, 2005
                                                            • 0 Attachment
                                                              Ambot Sakoy wrote:
                                                              >
                                                              > Not only the relative structure of your source documents but the
                                                              > other dimensions as well.

                                                              [...]

                                                              Tim should be known as the Devil's Advocate >-]

                                                              K
                                                            Your message has been successfully submitted and would be delivered to recipients shortly.