OASIS Darwin Information Typing Architecture (DITA) TC

  


Two key issues:


  
Who do we anticipate being the potential users of the base
package?
  
Michael, I want you to look at the current contents of the
language
reference material for both the base and technical content version. Is
this as you have been envisioning it?



  

Best,


Kris


Michael Priestley wrote:
OFD3E00C93.BD07FAEC-ON85257619.004E6B13-85257619.004EBB25@ca.ibm.com" type="cite">

  The point of a separate base package
is to provide the bare minimum of DITA support - just topic, map, basic
utility domain. 


  So absolutely everything else gets
relegated
out to another package - and since we've only got two other packages,
that
means they either go into tech docs or learning and training.


  I'm fine with renaming the tech doc
package to something else, if it helps - even "key specializations"
if that would do the trick. But if we move any specializations into the
base package, we undermine the point of having it.


  Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

  mpriestl@ca.ibm.com

  http://dita.xml.org/blog/25



  

    

      

        
"JoAnn
Hackos"
        <joann.hackos@comtech-serv.com>
        
        
08/20/2009 05:40 PM 
        
        

        

          

            

              

              
To
              
              
"Bruce Nevin
\(bnevin\)" <bnevin@cisco.com>,
              <dita@lists.oasis-open.org>
              
            
            

              

              
cc
              
              

          
            
            

              

              
Subject
              
              
RE: [dita] problem
with packaging of
glossaries
            
          
        

    
    
      
    
  




  I am in favor of Bruce’s
second
recommendation. What is the problem with stating that concept, task,
and
reference are key specializations in the DITA standard? Why should they
be relegated to technical communication only? I just don’t see the
point
of that. 

   

  Even if there is a All
DITA
package, we’re not including information about task, concept, and
reference
information types in the base architectural specification, but only in
the arch spec for technical communication. 

   

  I’ve never been in favor
of
this split and would strongly prefer that we include task, concept,
reference,
and glossary in the base architectural specification. That would leave
us with the machine industry specialization, which is, of course,
extremely
relevant for many outside the machine industry, and the various domains
(software, ui, programming, machine industry, safety hazard). Also
bookmap.
Why is bookmap considered relevant only for technical communication.
It’s
probably less relevant there and more relevant for DocBook aficionados.

   

  Since I’m writing the
tech
comm arch spec content and the topic content, I’d be very happy to
restore
task, concept, reference, and glossary to the base arch spec. I could
include
a statement that these may primarily relate to product documentation
although
I really don’t think that’s true. 

   

  JoAnn

   

  JoAnn Hackos
PhD

  President

  Comtech
Services,
Inc.

  joann.hackos@comtech-serv.com

  Skype
joannhackos

   

  

   

  
  


  


  From: Bruce Nevin (bnevin)
[mailto:bnevin@cisco.com] 

Sent: Thursday, August 20, 2009 11:24 AM

To: dita@lists.oasis-open.org

Subject: [dita] problem with packaging of glossaries

   

  This came
up
in the spec authoring meeting today. 

   

  The
problem:
<glossentry> is specialized from <concept>. <task>,
<concept>,
and <reference> are in the TechDocs package. This forces
<glossentry>
etc. to be restricted to the TD package.  But non-TechDocs folks need
glossaries, and support for them should be in the base.

   

  Two
solutions:

  1.        Accept
this. Present it as an unfortunate fait accompli for 1.2 -- if you want
a glossary, you have to use the TD package (or specialize your own).

  2.        Move
<task>, <concept>, and <reference> back into the
base,
sans TD-specific domain specializations, and include those
specializations
in the TD package. Present this as an interim step toward simplified
topics
being developed by the BusDocs SC.

  Comment?
Action?

   

     
/Bruce

Some potential users of the base package:
- people creating tools that work with
simple content applications with minimal structure, like unstructured blogs,
news feeds, web page components...
- people who would otherwise not read
the spec because it's too big, and can now be seduced into reading just
the first part, which provides a context that makes the rest less intimidating

Re the organization below - I'm not
sure about the order but the split looks right.

Thanks for making this discussion concrete.

Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





Kristen James Eberlein
<keberlein@pobox.com> 
08/21/2009 10:33 AM




To
DITA TC <dita@lists.oasis-open.org>


cc



Subject
Re: [dita] problem with packaging of
glossaries






Two key issues:
1.        Who
do we anticipate being the potential users of the base package?
2.        Michael,
I want you to look at the current contents of the language reference material
for both the base and technical content version. Is this as you have been
envisioning it?



Best,


Kris


Michael Priestley wrote: 


The point of a separate base package is to provide the bare minimum of
DITA support - just topic, map, basic utility domain. 



So absolutely everything else gets relegated out to another package - and
since we've only got two other packages, that means they either go into
tech docs or learning and training.



I'm fine with renaming the tech doc package to something else, if it helps
- even "key specializations" if that would do the trick. But
if we move any specializations into the base package, we undermine the
point of having it.



Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect 

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





"JoAnn Hackos"
<joann.hackos@comtech-serv.com>

08/20/2009 05:40 PM






To
"Bruce Nevin \(bnevin\)"
<bnevin@cisco.com>,
<dita@lists.oasis-open.org>



cc



Subject
RE: [dita] problem with packaging of
glossaries










I am in favor of Bruce’s second recommendation. What is the problem with
stating that concept, task, and reference are key specializations in the
DITA standard? Why should they be relegated to technical communication
only? I just don’t see the point of that.

  

Even if there is a All DITA package, we’re not including information about
task, concept, and reference information types in the base architectural
specification, but only in the arch spec for technical communication.

  

I’ve never been in favor of this split and would strongly prefer that
we include task, concept, reference, and glossary in the base architectural
specification. That would leave us with the machine industry specialization,
which is, of course, extremely relevant for many outside the machine industry,
and the various domains (software, ui, programming, machine industry, safety
hazard). Also bookmap. Why is bookmap considered relevant only for technical
communication. It’s probably less relevant there and more relevant for
DocBook aficionados. 

  

Since I’m writing the tech comm arch spec content and the topic content,
I’d be very happy to restore task, concept, reference, and glossary to
the base arch spec. I could include a statement that these may primarily
relate to product documentation although I really don’t think that’s
true.

  

JoAnn 

  

JoAnn Hackos PhD 

President 

Comtech Services, Inc. 

joann.hackos@comtech-serv.com


Skype joannhackos 

  



  









From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]


Sent: Thursday, August 20, 2009 11:24 AM

To: dita@lists.oasis-open.org

Subject: [dita] problem with packaging of glossaries


  

This came up in the spec authoring meeting today. 

  

The problem: <glossentry> is specialized from <concept>. <task>,
<concept>, and <reference> are in the TechDocs package. This
forces <glossentry> etc. to be restricted to the TD package.  But
non-TechDocs folks need glossaries, and support for them should be in the
base. 

  

Two solutions: 

1.        Accept
this. Present it as an unfortunate fait accompli for 1.2 -- if you want
a glossary, you have to use the TD package (or specialize your own).


2.        Move
<task>, <concept>, and <reference> back into the base,
sans TD-specific domain specializations, and include those specializations
in the TD package. Present this as an interim step toward simplified topics
being developed by the BusDocs SC. 

Comment? Action? 

  

    /Bruce 

  


Obviously, the files are currently sorted alphabetically. Do you have
an alternative that you would favor?


Best,


Kris


Michael Priestley wrote:
OF8717A807.2E55BDA2-ON85257619.0056A21F-85257619.00571583@ca.ibm.com" type="cite">

  Some potential users of the base
package:

  - people creating tools that work
with
simple content applications with minimal structure, like unstructured
blogs,
news feeds, web page components...

  - people who would otherwise not
read
the spec because it's too big, and can now be seduced into reading just
the first part, which provides a context that makes the rest less
intimidating


  Re the organization below - I'm not
sure about the order but the split looks right.


  Thanks for making this discussion
concrete.


  Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25



  

    

      

        
Kristen
James Eberlein
<keberlein@pobox.com> 
        
08/21/2009 10:33 AM
        
        
        

        

          

            

              

              
To
              
              
DITA TC
<dita@lists.oasis-open.org>
              
            
            

              

              
cc
              
              

          
            
            

              

              
Subject
              
              
Re: [dita] problem
with packaging of
glossaries
            
          
        

    
    
      
    
  




  Two key issues:

  1.        Who
do we anticipate being the potential users of the base package?

  2.        Michael,
I want you to look at the current contents of the language reference
material
for both the base and technical content version. Is this as you have
been
envisioning it?


  

  Best,


Kris


  

Hi Kris,

Maybe something like:

Topic elements
        Prolog
elements
        Body
elements
        Related-link
elements        
Map elements
        Basic
map elements
        Mapgroup
domain elements
        Subject
scheme elements
Shared elements
        Indexing
elements
        etc.
DITAVAL elements


I know I haven't captured everything
- but the basic thought would be to organize primarily around topic vs
map etc., and then within that distinction organize by order within the
doctype (when possible), or by general-to-specific or most-used to least-used
(when there is no doctype order).

If we were just laying out all elements,
then alpha order would make sense. But once we add groupings, then the
groupings aren't really useful in alpha order - they aren't things users
are looking up because they know about them, but things that add meaning
to the structure for users who don't know what they're looking for. So
the more meaning we can pack into the order the better.

Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





Kristen James Eberlein
<keberlein@pobox.com> 
08/21/2009 12:56 PM




To
Michael Priestley/Toronto/IBM@IBMCA


cc
DITA TC <dita@lists.oasis-open.org>


Subject
[dita] Order for lang ref files (Was
"Re: [dita] problem with packaging of glossaries")






Obviously, the files are currently sorted alphabetically.
Do you have an alternative that you would favor?


Best,


Kris


Michael Priestley wrote: 


Some potential users of the base package: 

- people creating tools that work with simple content applications with
minimal structure, like unstructured blogs, news feeds, web page components...


- people who would otherwise not read the spec because it's too big, and
can now be seduced into reading just the first part, which provides a context
that makes the rest less intimidating



Re the organization below - I'm not sure about the order but the split
looks right.



Thanks for making this discussion concrete.



Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect 

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





Kristen James Eberlein
<keberlein@pobox.com>

08/21/2009 10:33 AM






To
DITA TC <dita@lists.oasis-open.org>



cc



Subject
Re: [dita] problem with packaging of
glossaries









Two key issues: 

1.        Who do we anticipate
being the potential users of the base package? 

2.        Michael, I want you to
look at the current contents of the language reference material for both
the base and technical content version. Is this as you have been envisioning
it?




Best,


Kris

  


Here are some prototypes for discussion:


Base:
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/34012/base-langRef.gif

Technical Content:
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/34011/technicalContent-LangRef.gif


Best,


Kris


Michael Priestley wrote:
OFA706CE04.5E658925-ON8525761D.00522B5E-8525761D.0052E1F2@ca.ibm.com" type="cite">

  Hi Kris,


  Maybe something like:


  Topic elements

          Prolog
elements

          Body
elements

          Related-link
elements        

  Map elements

          Basic
map elements

          Mapgroup
domain elements

          Subject
scheme elements

  Shared elements

          Indexing
elements

          etc.

  DITAVAL elements



  I know I haven't captured everything
- but the basic thought would be to organize primarily around topic vs
map etc., and then within that distinction organize by order within the
doctype (when possible), or by general-to-specific or most-used to
least-used
(when there is no doctype order).


  If we were just laying out all
elements,
then alpha order would make sense. But once we add groupings, then the
groupings aren't really useful in alpha order - they aren't things
users
are looking up because they know about them, but things that add
meaning
to the structure for users who don't know what they're looking for. So
the more meaning we can pack into the order the better.


  Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25



  

    

      

        
Kristen
James Eberlein
<keberlein@pobox.com> 
        
08/21/2009 12:56 PM
        
        
        

        

          

            

              

              
To
              
              
Michael
Priestley/Toronto/IBM@IBMCA
              
            
            

              

              
cc
              
              
DITA TC
<dita@lists.oasis-open.org>
              
            
            

              

              
Subject
              
              
[dita] Order for
lang ref files (Was
"Re: [dita] problem with packaging of glossaries")
            
          
        

    
    
      
    
  




  Obviously, the files are currently sorted
alphabetically.
Do you have an alternative that you would favor?


Best,


Kris


Michael Priestley wrote: 

  

Some potential users of the base package: 

- people creating tools that work with simple content applications with
minimal structure, like unstructured blogs, news feeds, web page
components...
  

- people who would otherwise not read the spec because it's too big,
and
can now be seduced into reading just the first part, which provides a
context
that makes the rest less intimidating

  

Re the organization below - I'm not sure about the order but the split
looks right.

  

Thanks for making this discussion concrete.

  

Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect 

  mpriestl@ca.ibm.com

  http://dita.xml.org/blog/25


  
  

    

      

        
Kristen
James Eberlein
        <keberlein@pobox.com>
        
        
08/21/2009 10:33 AM
        
        
        

    

          

            

              

              
To
              
              
DITA TC <dita@lists.oasis-open.org>
              
            
            

              

              
cc
              
              

          
            
            

              

              
Subject
              
              
Re: [dita] problem
with packaging of
glossaries
            
          
        


    
    
      
    
  


  



Two key issues: 

1.        Who do we anticipate
being the potential users of the base package? 

2.        Michael, I want you to
look at the current contents of the language reference material for
both
the base and technical content version. Is this as you have been
envisioning
it?


  

Best,


Kris

  

  


Su-Laine, thanks for continuing to think about
this. I was operating under the following assumptions:



  
We need to separate the elements in the base
and technical packages.
  
We do not want to change any current
grouping of elements, for example, "Miscellaneous elements"


My TOC prototypes definitely reflect those
assumptions. Michael, can you offer a reality check about those
assumptions?


Kris


Su-Laine Yeo wrote:
BECDDDED92C3B949A38F5BC4BF56D21F0373304D@van-mail.jena.local" type="cite">
  
  

  
  

  
Hi everyone,
  

  
As I promised on Tuesday, here is a
suggestion for the
organization of the language reference. The numbers below are the ones
we're
using for DITA 1.1 (http://docs.oasis-open.org/dita/v1.1/CD02/langspec/ditaref-type.html).
Items without numbers are new for DITA 1.2. 
  

  
I will probably have some suggestions later
to rename some
of these items, but I’d rather not mix up a discussion on renaming with
a discussion
on organization. What do you think of this organization?
  

  
Cheers,
  
Su-Laine
  

  

  
Su-Laine Yeo
  
Interaction Design Specialist 
  
JustSystems Canada, Inc.
  
Office: 778-327-6356 
  
syeo@justsystems.com
  
www.justsystems.com 
  

  

  

  
--------------------------------------------------------------------
  
== Topic elements==
  
2.0 Topic elements (rename this, e.g. to
"topic structural
elements")
  
7.0 Body elements
  
8.0 Table elements
  
10.0 Related links elements
  
13.0 Typographic domain elements
  
17.0 Utilities domain elements
  

  
==Elements for specific topic types==
  
3.0 Concept elements
  
4.0 Reference elements
  
5.0 Task elements
  
Glossary related elements
  

  
==Map and bookmap elements==
  
19.0 Map elements
  
20.0 Map group elements
  
21.0 Bookmap content elements
  
22.0 Bookmap metadata elements
  

  
==Metadata elements==
  
9.0 Prolog elements
  
18.0 Indexing group elements
  
Classification domain elements
  
23.0 xNAL domain elements
  
Conref delayed resolution elements
  

  
==Industry-specific elements==
  
14.0 Programming elements
  
15.0 Software elements
  
16.0 User interface elements
  
Hazard statement elements
  
Machine industry task elements
  

  
==12.0 Specialization elements==
  

  

  
==Elements external to content==
  
Subject scheme map elements
  
24.0 DITAVAL elements
  

  
---------------------------------------------------
  
I suggest eliminating the "Miscellaneous
elements" group by putting these elements into meaningful categories:
  

  
Topic elements:
  
   11.01 dita 
  

  
Metadata elements:
  
    11.02 draft-comment
  
    11.04 indexterm
  
    11.05 indextermref
  
    11.06 index-base
  

  
Body elements:
  
    11.03 fn
  
    11.07 tm
  

  
Specialization elements
  
    11.08 data-about
  
    11.09 data
  
    11.10 foreign
  
    11.11 unknown
  

  

  

  

  

  

  
From:
Kristen James Eberlein
[mailto:keberlein@pobox.com]

  Sent: Tuesday, September 01, 2009 6:51 AM

  To: Michael Priestley

  Cc: DITA TC

  Subject: Re: [dita] Order for lang ref files (Was "Re: [dita]
problem with packaging of glossaries")
  
  
  

  
Here are some prototypes for discussion:


Base: http://www.oasis-open.org/apps/org/workgroup/dita/download.php/34012/base-langRef.gif

Technical Content: http://www.oasis-open.org/apps/org/workgroup/dita/download.php/34011/technicalContent-LangRef.gif


Best,


Kris


Michael Priestley wrote: 
  


  Hi
Kris,


  Maybe
something
like:


  Topic
elements

     
    Prolog elements

     
    Body elements

     
    Related-link elements        

  Map
elements

     
    Basic map elements

     
    Mapgroup domain elements

     
    Subject scheme elements

  Shared
elements

     
    Indexing elements

     
    etc.

  DITAVAL
elements



  I
know I
haven't captured everything - but the basic thought would be to
organize
primarily around topic vs map etc., and then within that distinction
organize
by order within the doctype (when possible), or by general-to-specific
or
most-used to least-used (when there is no doctype order).


  If
we were just
laying out all elements, then alpha order would make sense. But once we
add
groupings, then the groupings aren't really useful in alpha order -
they aren't
things users are looking up because they know about them, but things
that add
meaning to the structure for users who don't know what they're looking
for. So
the more meaning we can pack into the order the better.


  Michael
Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect

  mpriestl@ca.ibm.com

  http://dita.xml.org/blog/25


  
  

    

      

        

        
Kristen
James Eberlein <keberlein@pobox.com> 
        
08/21/2009
12:56 PM 
        
        

        

          

            

              

              
To
              
              

              
Michael
Priestley/Toronto/IBM@IBMCA 
              
            
            

              

              
cc
              
              

              
DITA TC <dita@lists.oasis-open.org>
              
              
            
            

              

              
Subject
              
              

              
[dita]
Order for lang ref files (Was "Re: [dita] problem with packaging of
glossaries")
              
            
          
        
        

        

        
      
    
  
  




Obviously, the files are currently sorted alphabetically. Do you have
an
alternative that you would favor?


Best,


Kris


Michael Priestley wrote:

  

Some potential users of the base package: 

- people creating tools that work with simple content applications with
minimal
structure, like unstructured blogs, news feeds, web page components...
  

- people who would otherwise not read the spec because it's too big,
and can
now be seduced into reading just the first part, which provides a
context that
makes the rest less intimidating

  

Re the organization below - I'm not sure about the order but the split
looks
right.

  

Thanks for making this discussion concrete.

  

Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect 

  mpriestl@ca.ibm.com

  http://dita.xml.org/blog/25
  
  

    

      

        

        
Kristen
James Eberlein <keberlein@pobox.com> 
        
08/21/2009
10:33 AM 
        
        

        

        

          

            

              

              
To
              
              

              
DITA TC <dita@lists.oasis-open.org>
              
              
            
            

              

              
cc
              
              

          
            
            

              

              
Subject
              
              

              
Re:
[dita] problem with packaging of glossaries
              
            
          
        
        

        

        
      
    
  
  





Two key issues: 

1.        Who do we anticipate being the potential
users of the base package? 

2.        Michael, I want you to look at the current
contents of the language reference material for both the base and
technical
content version. Is this as you have been envisioning it?



Best,


Kris


  
  

  

Re assumptions:

- yes we need to separate the elements
into base and technical
- but I think we can change the groupings,
and I think eliminating miscellaneous is a good goal.

Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





From:
Kristen James Eberlein <keberlein@pobox.com>

To:
Su-Laine Yeo <su-laine.yeo@justsystems.com>

Cc:
Michael Priestley/Toronto/IBM@IBMCA,
DITA TC <dita@lists.oasis-open.org>

Date:
09/03/2009 01:47 PM

Subject:
Re: [dita] Order for lang ref files
(Was "Re: [dita] problem with packaging of glossaries")





Su-Laine, thanks for continuing to think
about this. I was operating under the following assumptions:

We need to separate the elements in the
base and technical packages.
We do not want to change any current grouping
of elements, for example, "Miscellaneous elements"
My
TOC prototypes definitely reflect those assumptions. Michael, can you offer
a reality check about those assumptions?


Kris


Su-Laine Yeo wrote: 
Hi everyone,
 
As I promised on Tuesday, here is a suggestion
for the organization of the language reference. The numbers below are the
ones we're using for DITA 1.1 (http://docs.oasis-open.org/dita/v1.1/CD02/langspec/ditaref-type.html).
Items without numbers are new for DITA 1.2. 
 
I will probably have some suggestions later
to rename some of these items, but I’d rather not mix up a discussion
on renaming with a discussion on organization. What do you think of this
organization?
 
Cheers,
Su-Laine
 
 
Su-Laine Yeo
Interaction Design Specialist 
JustSystems Canada, Inc.
Office: 778-327-6356 
syeo@justsystems.com
www.justsystems.com

 
 
 
--------------------------------------------------------------------
== Topic elements==
2.0 Topic elements (rename this, e.g. to
"topic structural elements")
7.0 Body elements
8.0 Table elements
10.0 Related links elements
13.0 Typographic domain elements
17.0 Utilities domain elements
 
==Elements for specific topic types==
3.0 Concept elements
4.0 Reference elements
5.0 Task elements
Glossary related elements
 
==Map and bookmap elements==
19.0 Map elements
20.0 Map group elements
21.0 Bookmap content elements
22.0 Bookmap metadata elements
 
==Metadata elements==
9.0 Prolog elements
18.0 Indexing group elements
Classification domain elements
23.0 xNAL domain elements
Conref delayed resolution elements
 
==Industry-specific elements==
14.0 Programming elements
15.0 Software elements
16.0 User interface elements
Hazard statement elements
Machine industry task elements
 
==12.0 Specialization elements==
 
 
==Elements external to content==
Subject scheme map elements
24.0 DITAVAL elements
 
---------------------------------------------------
I suggest eliminating the "Miscellaneous
elements" group by putting these elements into meaningful categories:
 
Topic elements:
   11.01 dita 
 
Metadata elements:
    11.02 draft-comment
    11.04 indexterm
    11.05 indextermref
    11.06 index-base
 
Body elements:
    11.03 fn
    11.07 tm
 
Specialization elements
    11.08 data-about
    11.09 data
    11.10 foreign
    11.11 unknown
 
 
 
 
From: Kristen James Eberlein [mailto:keberlein@pobox.com]


Sent: Tuesday, September 01, 2009 6:51 AM

To: Michael Priestley

Cc: DITA TC

Subject: Re: [dita] Order for lang ref files (Was "Re: [dita]
problem with packaging of glossaries")
 
Here are some prototypes for discussion:


Base: http://www.oasis-open.org/apps/org/workgroup/dita/download.php/34012/base-langRef.gif

Technical Content: http://www.oasis-open.org/apps/org/workgroup/dita/download.php/34011/technicalContent-LangRef.gif


Best,


Kris


Michael Priestley wrote: 


Hi Kris,



Maybe something like:



Topic elements 

        Prolog elements


        Body elements


        Related-link elements      
  

Map elements 

        Basic map elements


        Mapgroup domain elements


        Subject scheme elements


Shared elements 

        Indexing elements


        etc.


DITAVAL elements




I know I haven't captured everything - but the basic thought would be to
organize primarily around topic vs map etc., and then within that distinction
organize by order within the doctype (when possible), or by general-to-specific
or most-used to least-used (when there is no doctype order).



If we were just laying out all elements, then alpha order would make sense.
But once we add groupings, then the groupings aren't really useful in alpha
order - they aren't things users are looking up because they know about
them, but things that add meaning to the structure for users who don't
know what they're looking for. So the more meaning we can pack into the
order the better.



Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect 

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





Kristen James Eberlein <keberlein@pobox.com>

08/21/2009 12:56 PM






To
Michael Priestley/Toronto/IBM@IBMCA



cc
DITA TC <dita@lists.oasis-open.org>



Subject
[dita] Order for lang ref files (Was "Re:
[dita] problem with packaging of glossaries")

 








Obviously, the files are currently sorted alphabetically. Do you have an
alternative that you would favor?


Best,


Kris


Michael Priestley wrote: 


Some potential users of the base package:


- people creating tools that work with simple content applications with
minimal structure, like unstructured blogs, news feeds, web page components...


- people who would otherwise not read the spec because it's too big, and
can now be seduced into reading just the first part, which provides a context
that makes the rest less intimidating



Re the organization below - I'm not sure about the order but the split
looks right. 


Thanks for making this discussion concrete.



Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect 

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25




Kristen James Eberlein <keberlein@pobox.com>

08/21/2009 10:33 AM

 





To
DITA TC <dita@lists.oasis-open.org>



cc



Subject
Re: [dita] problem with packaging of glossaries

 









Two key issues: 

1.        Who
do we anticipate being the potential users of the base package? 

2.        Michael,
I want you to look at the current contents of the language reference material
for both the base and technical content version. Is this as you have been
envisioning it?




Best,


Kris