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
