OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Re: [dita] Software Bias in Current DITA Design and Documentation

    Posted 01-17-2007 20:24
    Michael Priestley wrote:
    
    > The out-of-the-box task doctype explicitly supports task nesting as the 
    > more flexible of the two options.
    
    By this I assume you mean the ability to nest task topics inside other 
    topics.
    
    This is a reasonable solution, and it's my recommendation to our client 
    with the legacy data but it still seems more heavy-handed than necessary.
    
    I think the analogy I would draw would be section--if it is reasonable 
    to use section to subdivide concept or reference information, I think 
    it's equally reasonble to have a section-derived structure within task 
    to organize a task into a set of separately-title substeps when the 
    substeps don't really justify creating separate topics.
    
    Cheers,
    
    E.
    -- 
    W. Eliot Kimber
    Professional Services
    Innodata Isogen
    8500 N. Mopac, Suite 402
    Austin, TX 78759
    (214) 954-5198
    
    ekimber@innodata-isogen.com
    www.innodata-isogen.com
    
    


  • 2.  Re: [dita] Software Bias in Current DITA Design and Documentation

    Posted 01-17-2007 21:05

    I believe section is primarily for regular or repeating headings - the kinds of ones you would generate in a specialized case. Wouldn't these subtasks have unique titles, eg "Replacing the framitz"?

    The main difference between nesting topics and nesting sections would seem to be that topics require an ID - perhaps that is a bit heavy handed, if you're certain that the subtask will never be reused or referenced, but it doesn't seem like a bad precaution against reusers/referencers coming up with cases you didn't think of it when you created it.

    Sum: if you make the subtasks actual nested tasks, then reusers/referencers can make their own decisions about whether it can be useful in their context (a different question from whether it stands on its own). If you make them sections, then the reuser/referencer's options are limited.

    The rationale for identifying unique headings as topics is to err on the side of maintainability - if it's a heading, and it has unique information, then it's a legitimate destination for references, and it makes sense to enable it at creation time, rather than creating a bottleneck at first use that requires the destination to be edited to change it from section to topic.

    Michael Priestley
    IBM DITA Architect and Classification Schema PDT Lead
    mpriestl@ca.ibm.com
    http://dita.xml.org/blog/25



    "W. Eliot Kimber" <ekimber@innodata-isogen.com>

    01/17/2007 03:23 PM

    To
    Michael Priestley/Toronto/IBM@IBMCA
    cc
    <dita@lists.oasis-open.org>
    Subject
    Re: [dita] Software Bias in Current DITA Design and Documentation





    Michael Priestley wrote:

    > The out-of-the-box task doctype explicitly supports task nesting as the
    > more flexible of the two options.

    By this I assume you mean the ability to nest task topics inside other
    topics.

    This is a reasonable solution, and it's my recommendation to our client
    with the legacy data but it still seems more heavy-handed than necessary.

    I think the analogy I would draw would be section--if it is reasonable
    to use section to subdivide concept or reference information, I think
    it's equally reasonble to have a section-derived structure within task
    to organize a task into a set of separately-title substeps when the
    substeps don't really justify creating separate topics.

    Cheers,

    E.
    --
    W. Eliot Kimber
    Professional Services
    Innodata Isogen
    8500 N. Mopac, Suite 402
    Austin, TX 78759
    (214) 954-5198

    ekimber@innodata-isogen.com
    www.innodata-isogen.com