Certainly a good idea for DITA 1.3. A lot of the navigation and design of the DITA 1.2 spec was driven by our plan to deliver the documentation in three or four separate packages: Base, technical content, learning and training, and everything. OASIS didn't let us do this, and we ran out of time and energy to do a redesign and more improvements. I think the Element quick reference was a last minute addition to the spec. 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:45 AM, Jang F.M. Graat wrote: Hi Robert, I know there is an alphabetical list of elements in the specs. It may just be the awkward location of that list in the DITA 1.2 specs that makes people use a text search to find an element. Once you have found the element you are looking for, the Contains / Contained by tables are wonderful methods to traverse the DITA model, jumping from one element to its children or parents. I have used those tables more often than the table of contents or any other navigation. Taking the tables out of the text flow would be pretty devastating. Many products have a Quick Reference and usually that document is the first thing you find when opening the box. In the DITA 1.2 specs this Quick Reference is buried two levels deep in section 3.5. Moving it to where it should be (immediately after or even before the Table of Contents) would be an easy fix for a problem that is mainly disclosure - not availability - of information. 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 15:28, 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 --------------------------------------------------------------------- To unsubscribe, e-mail:
dita-unsubscribe@lists.oasis-open.org For additional commands, e-mail:
dita-help@lists.oasis-open.org