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

RE: [xml-doc] Out-of-the-Box DTDs, Schemas and Such

Expand Messages
  • Bowering, Chris
    John, When we were learning how to use XML as document source, we went two ways. One project rolled their own DTD. Another project used DocBook, without
    Message 1 of 24 , Mar 11, 2004
    • 0 Attachment
      John,

      When we were learning how to use XML as document source, we went two ways.
      One project rolled their own DTD. Another project used DocBook, without
      changes
      (http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook).

      After these projects were done, we needed to decide on a single, common
      solution for all product documentation. In the end we decided to go with a
      specialized version of DITA
      (http://www-106.ibm.com/developerworks/xml/library/x-dita1/).

      A roll-your-own seemed to be just too much wheel reinvention, and DocBook
      seemed to be just too big for our needs. In fact, because of its size and
      complexity, one of the assumptions we made with the DocBook option was that
      we would not change that DTD if adopted.

      DITA used the information typing model we had adopted a couple of years
      earlier and is designed to be specialized to fit specific needs. We have
      added, changed, and removed elements to fit our needs, but many of the core
      elements (for paragraphs, lists, tables, etc.) are out-of-the-box. In our
      case, it was the best way to go.

      Note that in all cases, the processing of the XML source into published
      documents (mostly HTML and PDF) is all in-house. Because we are merging
      information from many different development files (such as WSDLs) with our
      documentation source, and because we must adhere to corporate standards for
      the published documentation, our transformations and processors all must be
      customized no matter what DTD or schema we use for our documentation source.


      -Chris Bowering



      > -----Original Message-----
      > From: johnwh@... [mailto:johnwh@...]
      > Sent: Thursday, March 11, 2004 1:11 PM
      > To: xml-doc@yahoogroups.com
      > Subject: [xml-doc] Out-of-the-Box DTDs, Schemas and Such
      >
      >
      > I would enjoy hearing some feedback on the issue
      > of how practical and/or successful companies
      > have been with attempting a wholesale adoption
      > of existing DTDs, schemas and/or information
      > architectures for the in-house tech doc needs.
      >
      > Basically, it resolves down the following questions. This
      > may be oversimplifying the issues, but here goes.
      >
      > Say you have a large tech community supporting a
      > wide variety of document types and products (hardware,
      > software, installation guides, reference manuals,
      > technical notes, online help etc.). The documentation is, for
      > the most part, in FrameMaker and although it strictly follows defined
      > templates for formatting, it is not structured in the formal sense.
      >
      > Now in moving to structured authoring would it
      > be reasonable to think that one could use an existing DTDs (or set of
      > DTDs) that have already been developed for technical
      > documentation (i.e., DocBook, DITA, or whatever) and simply
      > do a wholesale adoption of an existing standard? I
      > am lead to believe by certain trainings I have attended
      > that these days there is really no need to be developing
      > DTDs or schemas for technical documentation from
      > scratch (i.e., why reinvent the wheel?).
      >
      > If these exist and are, in fact proving to be serviceable, I would
      > like to get some feedback on which standards are mainly
      > being used and perhaps some of the pros and cons that folks
      > have experienced with them.
      >
      > OR ...
      >
      > Is this really a pipe dream? And are most technical writing
      > organizations ending up developing their own in-house
      > DTDs/schemas? If so, is this because the existing out-
      > of-the-box standards turn out to be insufficient for
      > some reason? In other words, are folks mostly "rolling
      > their own," so to speak?
      >
      > The idea of every technical documentation organization
      > in the free world researching, developing, and maintaining
      > their own DTDs/schemas seems like huge amount of
      > redundancy. However, I have not yet tackled this issue
      > in practice on a large scale, so I would really appreciate
      > getting some comments from the trenches on this issue.
      >
      > To recap, should doc teams moving to structured authoring
      > be looking for out-of-the-box DTDs/shemas, or do they realistically
      > need to be prepared to develop them in-house? Or perhaps
      > there is a workable hybrid solution?
      >
      > Thanks in advance for any comments.
      >
      > John
      >
      >
      >
      >
      > Yahoo! Groups Links
      >
      >
      >
      >
      >
      >

      This message may contain privileged and/or confidential information. If you
      have received this e-mail in error or are not the intended recipient, you
      may not use, copy, disseminate or distribute it; do not open any
      attachments, delete it immediately from your system and notify the sender
      promptly by e-mail that you have done so. Thank you.


      [Non-text portions of this message have been removed]
    • melanie.kendell
      Hi John ... I am in exactly the space you are describing and, being new to this field, opted to take an existing standard and see how it fit. I went for
      Message 2 of 24 , Mar 11, 2004
      • 0 Attachment
        Hi John

        > Say you have a large tech community supporting a
        > wide variety of document types and products (hardware,
        > software, installation guides, reference manuals,
        > technical notes, online help etc.)...would it
        > be reasonable to think that one could use an existing DTD
        > that has already been developed for technical
        > documentation (i.e., DocBook, DITA, or whatever) and simply
        > do a wholesale adoption of an existing standard? I
        > am lead to believe by certain trainings I have attended
        > that these days there is really no need to be developing
        > DTDs or schemas for technical documentation from
        > scratch (i.e., why reinvent the wheel?).
        >
        > If these exist and are, in fact proving to be serviceable, I would
        > like to get some feedback on which standards are mainly
        > being used and perhaps some of the pros and cons that folks
        > have experienced with them.

        I am in exactly the space you are describing and, being new to this field, opted to take an existing standard and see how it fit. I went for DocBook as this seems to be the most widely used/supported DTD. In order to make it simpler for my fellow authors, I have earmarked all the DocBook stuff we won't need to use (being careful to preserve hierarchy elements that may not seem useful but are required if I want to use other elements).

        My next step was to create an EDD for Frame to allow us to use this subset for authoring. I am about half way through this - I imported a DocBook DTD, removed the elements I did not require, went through the General Rules to eliminate the removed elements and check the "requiredness" of the elements, and now I'm in the process of building the autoinsertion and text formating
        rules (this is being a bit bogged down as we didn't have an established template to work with).

        Some people may argue that you would be better off to start with the example DocBook DTD supplied with Frame, but (a) it is for an older version of DocBook; and (b) working through this has given me a far greater understanding of the EDD structure.

        At some stage in the future I intend to go back to DocBook itself and build a customisation layer for the DTD, but at this stage all the authors involved in the project will be using Frame as their editor so getting the EDD working is the priority.

        We have yet to start using this in earnest, but because I have a very clear view of the content architecture from my years as a technical communicator (doing online help using HATTs is a good training ground for XML) I don't forsee major problems. I am hopeful that everything (or almost everything) can be handled as a subset of DocBook rather than having to add extensions.

        I am also interested in how people are tackling this - and get an idea of how many people are in this problem space.

        Regards
        -Melanie
      • Sarah O'Keefe
        Hi John, This is an interesting question. ... In adopting an existing standard, you will need to make some customizations. These would likely include the
        Message 3 of 24 , Mar 12, 2004
        • 0 Attachment
          Hi John,

          This is an interesting question.

          At 10:10 AM 3/11/2004 -0800, you wrote:
          >Now in moving to structured authoring would it
          >be reasonable to think that one could use an existing DTDs (or set of
          >DTDs) that have already been developed for technical
          >documentation (i.e., DocBook, DITA, or whatever) and simply
          >do a wholesale adoption of an existing standard?

          In adopting an existing standard, you will need to make some
          customizations. These would likely include the following:

          * metadata
          You will probably want to establish metadata that is more specific to your
          organization than what a standard implementation provides out of the box.

          * elements
          Especially for a large DTD like DocBook, you will probably want to remove
          unneeded elements. (Conversely, if you start with a very small structure,
          you will want to add elements to the core structure.) You may also need to
          create a few new elements for your specific requirements.

          * transformation
          Most likely, you'll need to customize existing transformations to meet your
          formatting requirements.

          The question, then, is whether the effort to make these customizations to
          an existing DTD is greater than or smaller than the effort to create your
          own from scratch.

          My recommendation would be to analyze your existing documents and future
          requirements to determine what your ideal structure should look like. Once
          that analysis is completed, compare it to the existing standards to see
          what the effort would be to make them match.

          Regards,

          Sarah O'Keefe

          Disclaimer: We have a structured authoring solution for FrameMaker. And we
          do a lot of consulting on these issues.

          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          Sarah O'Keefe okeefe@...
          Scriptorium Publishing Services, Inc.
          DocFrame version 1.1 now shipping! XML in minutes, not months.
          http://www.scriptorium.com/docframe/
        • Charles Johnston
          Hi John, Most comments in this thread advise caution about creating a new DTD, but ... Maybe you want to do something no one else does - like us, we wanted to
          Message 4 of 24 , Mar 12, 2004
          • 0 Attachment
            Hi John,

            Most comments in this thread advise caution about creating a new DTD, but
            Sarah is right:

            >My recommendation would be to analyze your existing documents and future
            >requirements to determine what your ideal structure should look like.

            Maybe you want to do something no one else does - like us, we wanted to
            incorporate Information Mapping into our information structure, which ruled
            out DocBook.

            And I imagine Cisco is definitely big enough to justify doing things its own
            way, including having its own information structure.

            Seeing Cisco is so big, your problem would probably rather be how to
            evangelize your solution throughout the organization. So you would want to
            be looking at a pilot project to learn-by-doing and to demonstrate a
            successful implementation. Wish I could get to play at doing that at Cisco!

            Charles Johnston


            >From: "Sarah O'Keefe" <okeefe@...>
            >Reply-To: xml-doc@yahoogroups.com
            >To: xml-doc@yahoogroups.com
            >Subject: Re: [xml-doc] Out-of-the-Box DTDs, Schemas and Such
            >Date: Fri, 12 Mar 2004 08:39:40 -0500
            >
            >Hi John,
            >
            >This is an interesting question.
            >
            >At 10:10 AM 3/11/2004 -0800, you wrote:
            > >Now in moving to structured authoring would it
            > >be reasonable to think that one could use an existing DTDs (or set of
            > >DTDs) that have already been developed for technical
            > >documentation (i.e., DocBook, DITA, or whatever) and simply
            > >do a wholesale adoption of an existing standard?
            >
            >In adopting an existing standard, you will need to make some
            >customizations. These would likely include the following:
            >
            >* metadata
            >You will probably want to establish metadata that is more specific to your
            >organization than what a standard implementation provides out of the box.
            >
            >* elements
            >Especially for a large DTD like DocBook, you will probably want to remove
            >unneeded elements. (Conversely, if you start with a very small structure,
            >you will want to add elements to the core structure.) You may also need to
            >create a few new elements for your specific requirements.
            >
            >* transformation
            >Most likely, you'll need to customize existing transformations to meet your
            >formatting requirements.
            >
            >The question, then, is whether the effort to make these customizations to
            >an existing DTD is greater than or smaller than the effort to create your
            >own from scratch.
            >
            >My recommendation would be to analyze your existing documents and future
            >requirements to determine what your ideal structure should look like. Once
            >that analysis is completed, compare it to the existing standards to see
            >what the effort would be to make them match.
            >
            >Regards,
            >
            >Sarah O'Keefe
            >
            >Disclaimer: We have a structured authoring solution for FrameMaker. And we
            >do a lot of consulting on these issues.
            >
            >^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            >Sarah O'Keefe okeefe@...
            >Scriptorium Publishing Services, Inc.
            >DocFrame version 1.1 now shipping! XML in minutes, not months.
            >http://www.scriptorium.com/docframe/
            >
            >
            >
            >
            >
            >Yahoo! Groups Links
            >
            >
            >
            >
            >

            _________________________________________________________________
            Use MSN Messenger to send music and pics to your friends
            http://www.msn.co.uk/messenger
          • kadlec
            Hi, John - Use either the short or long DTD that comes with Frame 7... it meets the W3C Docbook standards and can t possibly be missing anything that you would
            Message 5 of 24 , Mar 12, 2004
            • 0 Attachment
              Hi, John -

              Use either the short or long DTD that comes with Frame 7... it meets the
              W3C Docbook standards and can't possibly be missing anything that you
              would need for formatting docs to XML.

              Better yet, use the XML Cookbook DTD that comes with Frame 7 - what a
              great resource that is!

              Good grief, John, you have the investment in the tool already; it's your
              best buy to get into XML. Once you have transformed your information to
              XML using Frame, you can move to any tool you like that works with XML..
              open standard; application and platform independent: it is a mantra. Go
              for it... it will be the single, most important work you can do for
              information orchestration at Cisco. Stop thinking of it in terms of
              moving the entire enterprise to another tool... You already have the
              tool(s)... and the DTDs.

              If your docs are truly well constructed FrameMaker, you can stay with
              FrameMaker (the easiest path and shortest learning curve) and move to
              Structured FrameMaker. They have some really neat tools for going from
              Standard to Structured already built right into their application. Use
              their Docbook and sample DTDs (they have a few available with the
              software upgrade). Take the training. After you have a few docs in XML
              and start moving them around to PDAs, laptops, browsers on the internet,
              you can decide if you want to change the DTD or build a new one for
              another purpose. DTDs are like the vocabulary base for your Cisco
              language and they will grow and change the more you use them.

              Use the DTD already created in Frame... learn it, tear it apart, rebuild
              it, throw it away and use someone else's DTD. All DTDs are related; they
              speak tag language and the tags are created using human language... you
              already speak the language! If you can read it, you can understand it -
              it's language, protecting language...

              If you build it, it will work... XML.. open standard; application and
              platform independent: it is a mantra <!--but not a religion-->

              MAKE A DECISION - HAVE A GREAT WEEKEND!


              You have nothing to lose and everything to gain.

              Thanks for listening.

              Sharon Kadlec
              InformationXDesign
              17715 Eureka Avenue West
              Farmington, MN 55024-9088
              952-463-3779
              kadlecweb@...



              -----Original Message-----
              From: johnwh@... [mailto:johnwh@...]
              Sent: Thursday, March 11, 2004 12:11 PM
              To: xml-doc@yahoogroups.com
              Subject: [xml-doc] Out-of-the-Box DTDs, Schemas and Such

              I would enjoy hearing some feedback on the issue
              of how practical and/or successful companies
              have been with attempting a wholesale adoption
              of existing DTDs, schemas and/or information
              architectures for the in-house tech doc needs.

              Basically, it resolves down the following questions. This
              may be oversimplifying the issues, but here goes.

              Say you have a large tech community supporting a
              wide variety of document types and products (hardware,
              software, installation guides, reference manuals,
              technical notes, online help etc.). The documentation is, for
              the most part, in FrameMaker and although it strictly follows defined
              templates for formatting, it is not structured in the formal sense.

              Now in moving to structured authoring would it
              be reasonable to think that one could use an existing DTDs (or set of
              DTDs) that have already been developed for technical
              documentation (i.e., DocBook, DITA, or whatever) and simply
              do a wholesale adoption of an existing standard? I
              am lead to believe by certain trainings I have attended
              that these days there is really no need to be developing
              DTDs or schemas for technical documentation from
              scratch (i.e., why reinvent the wheel?).

              If these exist and are, in fact proving to be serviceable, I would
              like to get some feedback on which standards are mainly
              being used and perhaps some of the pros and cons that folks
              have experienced with them.

              OR ...

              Is this really a pipe dream? And are most technical writing
              organizations ending up developing their own in-house
              DTDs/schemas? If so, is this because the existing out-
              of-the-box standards turn out to be insufficient for
              some reason? In other words, are folks mostly "rolling
              their own," so to speak?

              The idea of every technical documentation organization
              in the free world researching, developing, and maintaining
              their own DTDs/schemas seems like huge amount of
              redundancy. However, I have not yet tackled this issue
              in practice on a large scale, so I would really appreciate
              getting some comments from the trenches on this issue.

              To recap, should doc teams moving to structured authoring
              be looking for out-of-the-box DTDs/shemas, or do they realistically
              need to be prepared to develop them in-house? Or perhaps
              there is a workable hybrid solution?

              Thanks in advance for any comments.

              John




              Yahoo! Groups Links
            • melanie.kendell
              ... Information Mapping is a common enough methodology that it wouldn t be something that no one else does :) Our content structure is based on Information
              Message 6 of 24 , Mar 14, 2004
              • 0 Attachment
                Charles wrote:
                > Maybe you want to do something no one else does - like us, we
                > wanted to incorporate Information Mapping into our information
                > structure, which ruled out DocBook.

                Information Mapping is a common enough methodology that it wouldn't be something that no one else does :)

                Our content structure is based on Information Mapping and I have not (so far) found anything that cannot be mapped to DocBook. I'm intrigued - what DTD did you come up with and what specific things precluded DocBook as a solution.

                -Melanie
              • Saqib Ali
                ... Docbook Schema has such a insane number of tags that almost any kind of technical documentation can be mapped to DocBook. Which is a good thing. However
                Message 7 of 24 , Mar 14, 2004
                • 0 Attachment
                  > Our content structure is based on Information Mapping and I have not
                  > (so far) found anything that cannot be mapped to DocBook. I'm
                  > intrigued - what DTD did you come up with and what specific things
                  > precluded DocBook as a solution.

                  Docbook Schema has such a insane number of tags that almost any kind
                  of technical documentation can be mapped to DocBook. Which is a good
                  thing.

                  However due to this insane number of TAGs the authors can get confused
                  in deciding which tag to use. A common example is use of <section> TAG
                  vs <sectN>

                  ----Begin Example----
                  <section> versus <sectN> is largely a question of flexibility. The
                  stylesheets can make a <section> in a <section> look just like a
                  <sect2> within a <sect1>, so there's no output advantage.

                  But, a <section> within a <section> can be extracted into its own
                  top-level section, nested even more deeply, or moved to an entirely
                  different part of the document, without it and its own <section>
                  children being renamed. That is not true of the numbered section tags,
                  which are very sensitive to rearrangements. This can be easier for
                  authors who are new to DocBook than using <sectN>.

                  The main idea behind creating structured data is that it should be
                  easy to access and query. One should be able to retrieve a subsection
                  of any structured data, by using querying languages for XML (XPath and
                  XQuery). <sectN> are useful when traversing a document using
                  XPath/XQuery. <sectN> gives more flexibility, and control while
                  writing an XPath expression.

                  A well-defined, valid and well-structured document makes it easier for
                  one to write XPath/Query to retreive "specific" data from a
                  document.
                  For example you can use XPath to retrieve information in the <sect3>
                  block with certain attributes. However if you just used <section> for
                  all subsections, it becomes harder to retrieve the block of
                  information that you need.
                  ----End Example----

                  Ensuring which TAG <sectN> or <section> the author uses is very hard.
                  If multiple authors are working on the same document, it becomes very
                  important they remain consistent and use the right TAG in the right
                  place.
                • Saqib Ali
                  ... Ph by the way, I didn t mean that you shouldn t use DocBook. However I do think you should good policies for authors, which defines which TAG to use where.
                  Message 8 of 24 , Mar 14, 2004
                  • 0 Attachment
                    > Ensuring which TAG <sectN> or <section> the author uses is very hard.
                    > If multiple authors are working on the same document, it becomes very
                    > important they remain consistent and use the right TAG in the right
                    > place.

                    Ph by the way, I didn't mean that you shouldn't use DocBook. However I
                    do think you should good policies for authors, which defines which TAG
                    to use where.

                    In Peace,
                    Saqib Ali
                    -------------
                    http://validate.sf.net <---- (X)HTML / DocBook XML Validator and
                    Transformer
                  • melanie.kendell
                    Saqib wrote ... This is, I believe, why it is good practice to build in a customisation layer of some sort so you can restrict the number of tags presented to
                    Message 9 of 24 , Mar 14, 2004
                    • 0 Attachment
                      Saqib wrote
                      > However due to this insane number of TAGs the authors can get confused
                      > in deciding which tag to use. A common example is use of <section> TAG
                      > vs <sectN> ...
                      > Ensuring which TAG <sectN> or <section> the author uses is very hard.
                      > If multiple authors are working on the same document, it becomes very
                      > important they remain consistent and use the right TAG in the right
                      > place.

                      This is, I believe, why it is good practice to build in a customisation layer of some sort so you can restrict the number of tags presented to authors. It not only helps to maintain consistency, but also makes it easier for everyone to use :)

                      WRT <section> -v- <sectN> I think it very much depends on whether you are authoring content or documents - content should not have inherent hierarchy whereas documents will.

                      -Melanie Kendell
                    • Charles Johnston
                      Hi Melanie, Maybe this isn t the right place to discuss Information Mapping, but seeing ... But first, in relation to DocBook, you ve pointed yourself to part
                      Message 10 of 24 , Mar 15, 2004
                      • 0 Attachment
                        Hi Melanie,

                        Maybe this isn't the right place to discuss Information Mapping, but seeing
                        as it's sort-of related to DTDs and DocBook, I'll try to answer briefly:

                        >what DTD did you come up with and what specific things precluded DocBook as
                        >a solution

                        But first, in relation to DocBook, you've pointed yourself to part of the
                        reasoning:

                        >it is good practice to build in a customisation layer of
                        >some sort so you can restrict the number of tags presented to authors.

                        DocBook offers a huge number of elements, many of which aren't relevant and
                        which I don't want our authors to use, because this would introduce
                        inconsistency, as you point out.

                        It is my hope that we will eventually get all our developers (we are a
                        software biz) to write their documentation in XML (using whichever editors
                        they want), instead of them doing random things in Word (e.g writing all
                        their body text in a modified footnote style) - so the risk of inconsistency
                        grows by extending the authoring group to include anarchistic developers.

                        And, furthermore, if we extend the use of the DTD to our developers, will
                        DocBook's range of elements be sufficient? In spite of its huge number of
                        elements, there are some that I would like that it doesn't have (e.g. API,
                        Class, Method). Sure, one could use substitutes, but our developers would
                        doubtless still find things they wanted that aren't there. And remembering
                        the X in XML, I felt that if we had our own DTD, we could extend it as we
                        went along, e.g. to reflect the terminology/technology/concepts of the
                        industry we are in. I think we can only get developer-acceptance for
                        XML-based documentation if they feel the DTD reflects their unique
                        requirements.

                        I also wanted to incorporate Information Mapping into the DTD in a way that
                        was both visible and that could be validated. We were then a rapidly-growing
                        group of technical writers in a dotcom business (my, how things have
                        changed!) and there were no shared styles or methods. Information Mapping
                        was a way to get us all doing the same thing. Maybe I was wrong, but I
                        didn't believe you could map Information Mapping's structure to DocBook's -
                        perhaps you can fudge it, but I don't believe you can map it 1 to 1. And
                        while Information Mapping isn't a religion (we don't practice it 100%
                        perfectly), I do believe its structure helps reader comprehension. And there
                        would be little point in simultaneously introducing a new methodology and a
                        DTD that didn't support it!

                        All-in-all, four years ago DocBook didn't seem the right solution. Maybe I'd
                        choose differently today. Getting from XML based on a roll-your-own DTD to
                        other output formats (e.g through Cocoon) is much harder than getting from
                        XML based on DocBook, because you face an integration task.

                        Charles

                        >From: "melanie.kendell" <melanie.kendell@...>
                        >Reply-To: xml-doc@yahoogroups.com
                        >To: xml-doc@yahoogroups.com
                        >Subject: Re: [xml-doc] Out-of-the-Box DTDs, Schemas and Such
                        >Date: Mon, 15 Mar 2004 11:29:09 +1100
                        >
                        >
                        >Charles wrote:
                        > > Maybe you want to do something no one else does - like us, we
                        > > wanted to incorporate Information Mapping into our information
                        > > structure, which ruled out DocBook.
                        >
                        >Information Mapping is a common enough methodology that it wouldn't be
                        >something that no one else does :)
                        >
                        >Our content structure is based on Information Mapping and I have not (so
                        >far) found anything that cannot be mapped to DocBook. I'm intrigued - what
                        >DTD did you come up with and what specific things precluded DocBook as a
                        >solution.
                        >
                        >-Melanie
                        >
                        >
                        >
                        >
                        >
                        >Yahoo! Groups Links
                        >
                        >
                        >
                        >
                        >

                        _________________________________________________________________
                        Use MSN Messenger to send music and pics to your friends
                        http://www.msn.co.uk/messenger
                      • Saqib Ali
                        ... you are authoring content or documents - content should not have inherent hierarchy whereas documents will. I agree. But sometimes the distinction is
                        Message 11 of 24 , Mar 15, 2004
                        • 0 Attachment
                          > WRT <section> -v- <sectN> I think it very much depends on whether
                          you > are authoring content or documents - content should not have
                          inherent > hierarchy whereas documents will.

                          I agree. But sometimes the distinction is very hard.

                          Saqib Ali
                          -------------
                          http://validate.sf.net <---- (X)HTML / DocBook XML Validator and
                          Transformer
                        • Isaac Rabinovitch
                          ... I agree. But the fact that you have to build such a layer kind of eliminates any possibility of out of the box solutions.
                          Message 12 of 24 , Mar 15, 2004
                          • 0 Attachment
                            melanie.kendell wrote:

                            >Saqib wrote
                            >
                            >
                            >>However due to this insane number of TAGs the authors can get confused
                            >>in deciding which tag to use. A common example is use of <section> TAG
                            >>vs <sectN> ...
                            >>Ensuring which TAG <sectN> or <section> the author uses is very hard.
                            >>If multiple authors are working on the same document, it becomes very
                            >>important they remain consistent and use the right TAG in the right
                            >>place.
                            >>
                            >>
                            >
                            >This is, I believe, why it is good practice to build in a customisation layer of some sort so you can restrict the number of tags presented to authors. It not only helps to maintain consistency, but also makes it easier for everyone to use :)
                            >
                            >
                            >
                            I agree. But the fact that you have to build such a layer kind of
                            eliminates any possibility of "out of the box" solutions.
                          • melanie.kendell
                            Hi Charles ... That is the main advantage of Info Mapping. ... You may not be able to use the same name for things but I haven t had any difficulty mapping an
                            Message 13 of 24 , Mar 15, 2004
                            • 0 Attachment
                              Hi Charles

                              > We were then a rapidly-growing group of technical writers in a
                              > dotcom business (my, how things have changed!) and there were
                              > no shared styles or methods. Information Mapping was a way to
                              > get us all doing the same thing.

                              That is the main advantage of Info Mapping.

                              > Maybe I was wrong, but I didn't believe you could map
                              > Information Mapping's structure to DocBook's - perhaps you can
                              > fudge it, but I don't believe you can map it 1 to 1.

                              You may not be able to use the same name for things but I haven't had any difficulty mapping an Info Mapping type structure from DocBook elements.

                              > And while Information Mapping isn't a religion (we don't
                              > practice it 100% perfectly), I do believe its structure helps
                              > reader comprehension.

                              I must admit it was a long time ago since I did the Info Mapping course and I immediately discarded some of what was taught as not relevant (the template for example - which I saw as their way of wrapping common sense into a proprietary package) so I certainly couldn't call myself an Info Mapping purist.

                              > And there would be little point in simultaneously introducing a new
                              > methodology and a DTD that didn't support it!

                              Yes, if you were only just learning/promoting Info Mapping you would want to reinforce it using all the right terms so I can see why you went the route you did.

                              > All-in-all, four years ago DocBook didn't seem the right solution.
                              > Maybe I'd choose differently today. Getting from XML based on a
                              > roll-your-own DTD to other output formats (e.g through Cocoon) is
                              > much harder than getting from XML based on DocBook, because you
                              > face an integration task.

                              Which is why I've gone the DocBook subset route - I still have to do work on the customisation layer and customise any transforms (as Isaac wrote "the fact that you have to build such a layer kind of eliminates any possibility of "out of the box" solutions"), but it makes it easier at each step to start work from a "bought" example than from scratch.

                              As with any implementation, and as gets mentioned here often, each set of circumstances is different and good analysis is the only way to foster a good result.

                              What I would like to see is more sharing of the outcomes of our individual analyses - I have yet to finish my EDD for Frame (let alone my proper DocBook customsation layer) but when it is I will be happy to put my files up on the group website. How about those of you that are further down the track publishing your DTDs, transforms, etc?

                              -Melanie
                            • John OGorman
                              ... I m not certain if my first reply posted properly - I don t see it on the group list yet...so I will give a quick summary of my reply to John s question
                              Message 14 of 24 , Mar 17, 2004
                              • 0 Attachment
                                --- In xml-doc@yahoogroups.com, johnwh@c... wrote:
                                > I would enjoy hearing some feedback on the issue
                                > of how practical and/or successful companies
                                > have been with attempting a wholesale adoption
                                > of existing DTDs, schemas and/or information
                                > architectures for the in-house tech doc needs.

                                I'm not certain if my first reply posted properly - I don't see it on
                                the group list yet...so I will give a quick summary of my reply to
                                John's question about approaches.

                                Most of the responses seem to lean toward a hybrid approach and I
                                would add one observation and a suggestion.

                                My observation is that many of the attempts at markup that I have
                                seen have the document 'carry' way too much weight in terms of
                                knowledge, syntax, and semantics in addition to structure.

                                My suggestion to lighten the load is to further separate (as XML is
                                designed to do) the product you are documenting from the information
                                that supports it, and yet again from the structure that optimizes and
                                delivers that knowledge.

                                When you do your content analysis, consider thinking about placing
                                components of your current documentation set into three piles:

                                Product components (routers, hubs, connectors, etc.) If you were
                                going to draw a picture of a system this is what would be in the
                                drawing.

                                Knowledge components. If your task was to simply describe each of the
                                Product components, you would 'attach' a knowledge component
                                (possibly a Description) to each. This is where information mapping
                                comes into its own: descriptions, procedures, concepts, etc.

                                Delivery components. These are the structural components of the
                                delivery aspect of your project. Book components, web components,
                                Help components can all be managed in the delivery domain.

                                From a single source perspective, what should start to notice is that
                                there will be knowledge common to all Cisco products; there will be
                                knowledge common to all Cisco routers; there will be knowledge common
                                to all Cisco hubs, and so on. Also, you should start to see similar
                                layering in the Delivery domain.

                                Doing this helps to create a clear distinction between a common
                                knowledge component, like "How to Contact Cisco Systems" and a
                                delivery-specific component like "About This Book".

                                Thanks for letting me participate in the discussion.
                              • Jirka Kosek
                                ... You can create your custom subset of DocBook omitting all unused elements. This will create strict editing environment for your developers and you still be
                                Message 15 of 24 , Mar 19, 2004
                                • 0 Attachment
                                  Charles Johnston wrote:

                                  > DocBook offers a huge number of elements, many of which aren't relevant and
                                  > which I don't want our authors to use, because this would introduce
                                  > inconsistency, as you point out.

                                  You can create your custom subset of DocBook omitting all unused
                                  elements. This will create strict editing environment for your
                                  developers and you still be able to use a lot of existing DocBook tools.

                                  > And, furthermore, if we extend the use of the DTD to our developers, will
                                  > DocBook's range of elements be sufficient? In spite of its huge number of

                                  You can always extend DocBook. It is quite common practise to create
                                  extended subsets of DocBook.

                                  > elements, there are some that I would like that it doesn't have (e.g. API,
                                  > Class, Method).

                                  API ~ interfacename element
                                  class ~ classname element
                                  method ~ methodname element

                                  They were added with other OO related elements between V3 and V4 of
                                  DocBook. If your business is to write software documentation you should
                                  find all necessary elements in DocBook. If not, you can always ask
                                  DocBook TC to add new element if it's general enough.

                                  Jirka

                                  --
                                  -----------------------------------------------------------------
                                  Jirka Kosek
                                  e-mail: jirka@...
                                  http://www.kosek.cz


                                  [Non-text portions of this message have been removed]
                                • Charles Johnston
                                  Thank you, Jirka - that is a very precise response (not one superfluous word!) and clear evidence that I must revisit DocBook! Charkes ...
                                  Message 16 of 24 , Mar 19, 2004
                                  • 0 Attachment
                                    Thank you, Jirka - that is a very precise response (not one superfluous
                                    word!) and clear evidence that I must revisit DocBook!

                                    Charkes


                                    >From: Jirka Kosek <jirka@...>
                                    >Reply-To: xml-doc@yahoogroups.com
                                    >To: xml-doc@yahoogroups.com
                                    >Subject: Re: [xml-doc] Out-of-the-Box DTDs, Schemas and Such
                                    >Date: Fri, 19 Mar 2004 17:18:52 +0100
                                    >
                                    >Charles Johnston wrote:
                                    >
                                    > > DocBook offers a huge number of elements, many of which aren't relevant
                                    >and
                                    > > which I don't want our authors to use, because this would introduce
                                    > > inconsistency, as you point out.
                                    >
                                    >You can create your custom subset of DocBook omitting all unused
                                    >elements. This will create strict editing environment for your
                                    >developers and you still be able to use a lot of existing DocBook tools.
                                    >
                                    > > And, furthermore, if we extend the use of the DTD to our developers,
                                    >will
                                    > > DocBook's range of elements be sufficient? In spite of its huge number
                                    >of
                                    >
                                    >You can always extend DocBook. It is quite common practise to create
                                    >extended subsets of DocBook.
                                    >
                                    > > elements, there are some that I would like that it doesn't have (e.g.
                                    >API,
                                    > > Class, Method).
                                    >
                                    >API ~ interfacename element
                                    >class ~ classname element
                                    >method ~ methodname element
                                    >
                                    >They were added with other OO related elements between V3 and V4 of
                                    >DocBook. If your business is to write software documentation you should
                                    >find all necessary elements in DocBook. If not, you can always ask
                                    >DocBook TC to add new element if it's general enough.
                                    >
                                    > Jirka
                                    >
                                    >--
                                    >-----------------------------------------------------------------
                                    > Jirka Kosek
                                    > e-mail: jirka@...
                                    > http://www.kosek.cz
                                    >
                                    >
                                    >[Non-text portions of this message have been removed]
                                    >
                                    >
                                    >
                                    >
                                    >Yahoo! Groups Links
                                    >
                                    >
                                    >
                                    >
                                    >

                                    _________________________________________________________________
                                    Express yourself with cool new emoticons http://www.msn.co.uk/specials/myemo
                                  • John OGorman
                                    I would like to split this thread, if anyone is interested, and get the group s feedback on an idea I have been working on. I touched on it in my reply to John
                                    Message 17 of 24 , Mar 23, 2004
                                    • 0 Attachment
                                      I would like to split this thread, if anyone is interested, and get
                                      the group's feedback on an idea I have been working on. I touched on
                                      it in my reply to John and his question about OOTB DTDs, etc.

                                      > >API ~ interfacename element
                                      > >class ~ classname element
                                      > >method ~ methodname element

                                      My question to the group is this:

                                      Does the inclusion of elements like 'API' in DocBook create
                                      difficulties for technical writers who are trying to implement a
                                      single-source solution for example? Isn't one of the challenges in
                                      creating a manageable collection of documentation to limit the number
                                      of specialized 'forms'?

                                      My solution has been to create the four domains I mentioned in my
                                      reply to John from Cisco: Customer, Product, Documentation, and
                                      Delivery. The rule is that any objects that belong to a single domain
                                      can be listed and even specialized by other objects in that domain;
                                      however, cross-domain specialization can only occur in a solution
                                      space and only then by linking elements.

                                      Is there any interest in pursuing this? The architecture suggests
                                      some interesting solutions to issues like single-sourcing in a mulit-
                                      lingual environment, for example.

                                      Thanks for your collective consideration.
                                    • melanie.kendell
                                      Hi John ... I would be *very* interested in pursuing this, especially where it touches on multi-lingual content. For clarification, what sorts of things do you
                                      Message 18 of 24 , Mar 23, 2004
                                      • 0 Attachment
                                        Hi John

                                        > My solution has been to create the four domains I mentioned in my
                                        > reply to John from Cisco: Customer, Product, Documentation, and
                                        > Delivery. The rule is that any objects that belong to a single
                                        > domain can be listed and even specialized by other objects in that
                                        > domain; however, cross-domain specialization can only occur in a
                                        > solution space and only then by linking elements.
                                        >
                                        > Is there any interest in pursuing this? The architecture suggests
                                        > some interesting solutions to issues like single-sourcing in a
                                        > mulit-lingual environment, for example.

                                        I would be *very* interested in pursuing this, especially where it touches on multi-lingual content. For clarification, what sorts of things do you expect to go into your four categories (I can probably guess some, but I'd rather get it from the horses mouth so to speak)?

                                        Would this be something based on DocBook or another standard or would it be a brand new "standard".

                                        -Melanie
                                      • John OGorman
                                        ... wrote: For clarification, what sorts of things do you expect to go into your four categories (I can probably guess some, but I d
                                        Message 19 of 24 , Mar 24, 2004
                                        • 0 Attachment
                                          --- In xml-doc@yahoogroups.com, "melanie.kendell"
                                          <melanie.kendell@b...> wrote:

                                          For clarification, what sorts of things do you expect to go into
                                          your four categories (I can probably guess some, but I'd rather get
                                          it from the horses mouth so to speak)?
                                          >
                                          > Would this be something based on DocBook or another standard or
                                          would it be a brand new "standard".
                                          >
                                          > -Melanie

                                          You gotta love that enthusiasm...I know I do!

                                          *** This is a longish reply. Apologies to the dictum that brevity is
                                          the soul of wit... um, or something like that. ***

                                          I should preface my response by saying that I'm not very adept, yet,
                                          at the technical side of xml. I like xml's main assertion that the
                                          separation of content and presentation creates a more managable
                                          authoring environment, and I'm proposing to extend that a bit.

                                          The strength of the argument for a different information architecture
                                          lies in the patterns of usage that began to emerge from my attempts
                                          to create a content model for multi-lingual on-line Help systems.

                                          What I am proposing is one further separation: The information that a
                                          user needs to do his or her job should be separate from the
                                          structural representation of the document that contains the
                                          information. This structure should be, as it is now in xml, separate
                                          from the presentation option, like web, Help, or print doc.

                                          The result of this three-way separation is that information typing
                                          (for lack of a better term) can be applied strictly to the
                                          information layer. In a task-based documentation environment, the
                                          decision on which content is presented can then be made based on four
                                          questions:

                                          1. What objective is my Customer trying to accomplish?
                                          2. What part(s) of the Product are they using to optimize the chances
                                          of achieving their objective?
                                          3. What type of Information do they require to optimize the Product
                                          experience?
                                          4. How should my application optimize the Delivery of the content?

                                          One provocative comment at this point: optimization is optional. My
                                          customer does not need my product to DO his job, he needs my product
                                          to OPTIMIZE his chances of success. Likewise, my product does not
                                          REQUIRE documention, however it does make the product experience more
                                          rewarding. Just to drive the point home, information does not need to
                                          be organized, highlighted, bulleted, or boxed. These structural
                                          features do, in fact, add value.

                                          My assertion is that the separation of objects into a pure
                                          information layer provides an opportunity to focus on just what the
                                          customer needs. It coincidentally supplies a very tidy way of tagging
                                          the objects for id, information type, language, status, location,
                                          etc. and opens the door for association to a Product object (likewise
                                          tagged) in a relationship that lends itself to things like
                                          internationalization.

                                          There is lots more detail, but I will leave you with a scenario from
                                          my days as a product documentation architect.

                                          Internationalization requires 100% separation of code from human-
                                          readable content. Say I have a product with only one dialog box for
                                          users to access. Let's say all of the code (Product) components in
                                          the dialog box are tagged and all of the descriptions (Information)
                                          of the components are tagged, and the dialog itself is designed to
                                          optimize the experience of: "Add an Extends to Oracle" and that the
                                          documentation includes instructions for doing just that in English.
                                          What this new architecture says is that the structure of the dialog
                                          box belongs to the Product domain; the content - which can be
                                          separately translated into any number of languages - belongs to the
                                          Information domain. The components that I use to optimize the
                                          delivery - be it web, WAP, Doc, or Help - are components of the
                                          Delivery domain.

                                          The important thing is that the Information is stand-alone: at a
                                          minimum (read: non-optimized), users can get the information they
                                          need. Also, since the objective at hand is the same ** regardless of
                                          the language of the user **, translated content can be 'attached' to
                                          the same product component, and the same scripts that load the
                                          content into a delivery mode can be used independent of language.

                                          Finally, I don't think I'm proposing a new standard. I'm more
                                          familiar with DITA as a way of specializing content, but what I'm
                                          proposing might be to at least think about separating product domain
                                          objects, like APIs, from both information about product domain
                                          objects and the presentation forms of information objects.
                                        • Michael Priestley
                                          ... Limit, or manage: DITA s approach is to allow different groups to create their own specialized forms while supporting interoperability through common
                                          Message 20 of 24 , Mar 25, 2004
                                          • 0 Attachment
                                            John OGorman writes:

                                            >Does the inclusion of elements like 'API' in DocBook create
                                            >difficulties for technical writers who are trying to implement a
                                            >single-source solution for example? Isn't one of the challenges in
                                            >creating a manageable collection of documentation to limit the number
                                            >of specialized 'forms'?

                                            Limit, or manage: DITA's approach is to allow different groups to
                                            create their own specialized forms while supporting interoperability
                                            through common ancestor types.

                                            >My solution has been to create the four domains I mentioned in my
                                            >reply to John from Cisco: Customer, Product, Documentation, and
                                            >Delivery. The rule is that any objects that belong to a single domain
                                            >can be listed and even specialized by other objects in that domain;
                                            >however, cross-domain specialization can only occur in a solution
                                            >space and only then by linking elements.

                                            Not sure about this. When you posted your reply to John, it immediately
                                            made me think of DITA, where we have specialization of information types
                                            (concept vs. task, for example), specialization of domains (programming
                                            documentation versus user interface documentation, for example), and
                                            the separation of content (topics) from context (maps) which allows the
                                            reuse of topics in delivery vehicles with different structural requirements
                                            (books versus webs versus help sets). Additional delivery issues could be
                                            handled by customizing the standard transforms for a given set of
                                            information,
                                            and conditional processing based on metadata.

                                            It sounds to me like we're talking about the same kinds of issues, and
                                            most importantly the separation of these issues so they can be solved in
                                            ways
                                            that don't interferer with each other. But I'm not sure how the solution
                                            you're proposing would compare to the solution we've arrived at with DITA.

                                            Michael Priestley
                                            DITA Specialization Architect
                                          • John OGorman
                                            ... The architecture I m thinking about is very similar to DITA, with one notable exception. The devil, they say, is in the details. In my model, the
                                            Message 21 of 24 , Mar 26, 2004
                                            • 0 Attachment
                                              Michael Priestly writes:

                                              > Limit, or manage: DITA's approach is to allow different groups to
                                              > create their own specialized forms while supporting interoperability
                                              > through common ancestor types.

                                              The architecture I'm thinking about is very similar to DITA, with one
                                              notable exception. The devil, they say, is in the details. In my
                                              model, the responsibility for details in each domain belong to the
                                              owners of that domain. Specialization in domains is completely
                                              independent of specialization in other domains. It is at the same
                                              time managed so that the same factors of specialization apply to each
                                              domain. There are limits, in other words, in each domain to the
                                              number and diversity of species. Where there are fewer constraints is
                                              the number of available combinations of species.

                                              What I'm proposing is to place some boundaries on the direction and
                                              extent of specialization, while at the same time suggesting that
                                              members of different domains, like interface objects and
                                              documentation objects should have different common ancestors and be
                                              associated by linking - in a functional domain - their respective
                                              unique identification strings.

                                              > It sounds to me like we're talking about the same kinds of issues,
                                              > and most importantly the separation of these issues so they can be
                                              > solved in ways that don't interferer with each other. But I'm not
                                              > sure how the solution you're proposing would compare to the
                                              >solution we've arrived at with DITA.

                                              We are absolutely on the same page, pardon the pun. The only place we
                                              differ a bit is in the management, to extend the DITA metaphor, of
                                              the concept of 'Kingdoms' or Domains. Members of the plant and
                                              animal and mineral kingdoms may have come from the same ancestors
                                              long ago, but for practical purposes they are very different.

                                              An example may help illustrate what I have in mind. Let's say that in
                                              my information kingdom, I have seven or eight different forms
                                              (species) of documentation. They might follow closely along the
                                              information mapping guidelines: description, instruction, etc. I can
                                              use DITA very effectively to differentiate one type from another.

                                              In my product kingdom, I have several species of programming and
                                              interface objects. They are viable in their own right, yet use
                                              variables similar to the ones used in the information layer to
                                              distinguish themselves from each other.

                                              Associating an interface object with an information object creates an
                                              instance of interface documentation, but in my model this would not
                                              be a true species. This would be a symbiot. Each species is free to
                                              evolve in whatever direction it needs to individually without
                                              affecting ancestry in the other three kingdoms.

                                              To go back to the internationalization issue for a second, if I build
                                              software using the new architecture, I believe I can more easily
                                              separate code objects from information objects, then using a 're-
                                              assembly script' use the unique identifiers to build a product with
                                              whatever language my customer needs.
                                            • John OGorman
                                              I d like to re-start this discussion if I might. First of all, I should have read the DITA spec a little more closely before I went galloping off in that
                                              Message 22 of 24 , Mar 29, 2004
                                              • 0 Attachment
                                                I'd like to re-start this discussion if I might.

                                                First of all, I should have read the DITA spec a little more closely
                                                before I went galloping off in that direction. The last time I read
                                                it was in 2001, and I liked it then. Subsequent work has only
                                                reinforced my initial impression and I have no pretensions to
                                                creating a new standard, never mind replacing one. I just wanted to
                                                see if a new way of thinking about and describing topics would
                                                successfully extend it.

                                                My original intention was to propose an extension to what is a very
                                                robust architecture, and I should have stuck with that. The four
                                                areas I mentioned: Customer, Product, Documentation, and Delivery
                                                still stand as functional domains, but what I should have done was
                                                started with the proposed model for managing those topics in an
                                                enterprise context, then worked forward into the four domains.

                                                Here is the idea I should have introduced at the beginning:

                                                To be managed effectively in an enterprise context, objects, in
                                                addition to having a unique identifier, must have at least one
                                                variable from each of six informational dimensions: Form, Ownership,
                                                Status, Location, Function, and Task.

                                                (In my cosmology, DITA lives in the 'form' dimension.)

                                                When you take this approach, an 'ownership' pattern starts to
                                                develop: different disciplines control different forms. Also, in the
                                                context of your company's business, three domains begin to take
                                                shape: Product, Documentation, and Delivery. I spoke about these in a
                                                previous post, so I won't go into any more detail here, except to say
                                                that every company has these three information pools.

                                                In addition to the ownership pattern, there should be evidence of
                                                a 'forms' pattern as well. For example, the structures of 'product'
                                                forms are different from the structures of 'information' forms are
                                                different than the structure of 'delivery' forms.

                                                Finally, when businesses interact, there is a "Customer" relationship
                                                established that supplies the context for the other three. In
                                                addition to the three internal domains that each company has, the
                                                existence of this relationship creates the need for forms in a fourth
                                                domain.

                                                So, going back to my original proposal, if as a purveyor of
                                                information you know your customer's objective and your product's
                                                function, you can supply that customer with all forms of information
                                                relevant to the completion of that task in an optimized delivery
                                                context.

                                                One of the keys to making all of that work is the application of the
                                                six informational dimensions in the architecture, which I call Q6, to
                                                all business entities to which topics can be attached: people,
                                                places, things, time, function, and instruction.

                                                Along with the four functional domains, this method of describing the
                                                forms within those domains leads me to propose that specialization
                                                can occur in two ways: evolution, as detailed in the DITA model; and,
                                                covolution - the combination of two or more structures to form a
                                                third.
                                              Your message has been successfully submitted and would be delivered to recipients shortly.