Re: [dita] Order for lang ref files (Was "Re: [dita] problem withpackagi

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

dita message