Re: [dita] problem with packaging of glossaries

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



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





From:
Kristen James Eberlein <>

To:
Su-Laine Yeo <>

Cc:
Michael Priestley/Toronto/IBM@IBMCA,
DITA TC <>

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 

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:]


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 



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





Kristen James Eberlein <>

08/21/2009 12:56 PM






To
Michael Priestley/Toronto/IBM@IBMCA



cc
DITA TC <>



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 



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




Kristen James Eberlein <>

08/21/2009 10:33 AM

 





To
DITA TC <>



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