Re: [dita] DITA 1.3 documentation -- shall we remove the Contains and "Contains by" tables

[Kristen James Eberlein <kris@eberleinconsulting.com>]

Hi, Robert.

We are thinking on the same lines ...

I ran some checks having the Contains and "Contains by" content in an appendix, with hyperlinks from the individual Language Reference topics. It greatly improves the search experience, and also would make it easy for people to print content.

I'm very glad that everyone is chiming in on this thread. With so much participation, we'll improve the spec experience for DITA 1.3. We've got enough lead time ...

Best,
Kris

Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)

On 9/12/2012 9:28 AM, Robert D Anderson wrote:

For what it's worth, we tried having an alphabetical list of elements at
the end of the language section, but something tells me it isn't being
noticed by most people. I'm not sure how to improve that. The lists are
available with a couple of groupings, or as one long list:
http://docs.oasis-open.org/dita/v1.2/os/spec/element-quick-reference.html

A couple of ideas - the specification previously came in multiple docs
(architectural specification and language specification). We could have a
companion doc that is part of the specification deliverable, linked to from
the main page (like we link to the DTDs and XSDs), and store the
contains/contained-by items in there (linked to from the main language
spec). That could be done as a single doc, or as individual docs (which
would easily let us include only the learning modules with a future
learning package). If we did that, and if we found a way to simplify the
attribute tables (big if), then the PDF could conceivably become small
enough to print out. I know, a fantasy...

A less advanced idea would be to store the content models in an appendix,
which would at least mean that a search from the front of the PDF would hit
the element descriptions before hitting the content models.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://dita-ot.sourceforge.net/)



From:	"Jang F.M. Graat" <jang@jang.nl>
To:	DITA TC <dita@lists.oasis-open.org>
Date:	09/12/2012 00:58
Subject:	Re: [dita] DITA 1.3 documentation -- shall we remove the
            Contains and "Contains by" tables
Sent by:	<dita@lists.oasis-open.org>



Hello all,

I agree with Tony that the problem is the search method, not its
availability. Having an alphabetical list of elements, possibly having more
than one such list - grouped per domain - as hyperlinks in an obvious
location (appendix ? or up front immediately following the TOC) would do a
lot of good for readers of the specs. Full text search is a must if you
want to find that certain phrase you know you have seen before but
forgotten where. Paging through those 1200 pages to find the phrase is
almost impossible to do. Killing the full text search because some people
use it in the wrong way is a bad choice. Removing the tables is a bad
choice, too. Rethinking possible ways of disclosing the information is a
good one.

Ciao

Jang

JANG Communication
Coaching - Copywriting - Consulting
Amsterdam - Netherlands
Tel.  +31 20 755 8466
Cell +31 6 5478 1632
http://www.jang.nl

On 12 sep. 2012, at 02:54, Tony Self wrote:

Greetings all

If the problem is in text searching in PDFs, could we guide readers to

using the index as a means of better locating information? While disabling
the search function would push readers to use the index, it may cause more
angst than it relieves. Sorry this isn’t a brilliant solution, but I
suspect there isn’t one!

Cheers

Tony Self



From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On

Behalf Of Kristen James Eberlein

Sent: Wednesday, 12 September 2012 6:50 AM
To: DITA TC
Subject: [dita] DITA 1.3 documentation -- shall we remove the Contains

and "Contains by" tables

As we start working on DITA 1.3 documentation, we need to consider

whether to include the Contains and "Contains by" tables in the Language
Reference topics.

Pro = Useful information
Con = Makes it impossible to search the spec and find information about a

specific element, since there are so many false hits. For example, if you
search the PDF version for indexterm, you get over 130 false hits before
you land on the actual topic.

Best,
Kris

Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)

---------------------------------------------------------------------
To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: dita-help@lists.oasis-open.org