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

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

Expand Messages
  • 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 1 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 2 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 3 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 4 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.