[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] DITA 1.3 documentation -- shall we remove the Contains and "Contains by" tables
I use the HTML version, so that would be fine with me. Thanks and best regards, --Scott Scott Hudson | Pelco by Schneider Electric | United States | Standards Lead Ph: +1-970-282-1952 | M: +1-720-663-7268 | Site: pdn.pelco.com | scott.hudson@schneider-electric.com On 9/12/12 8:34 AM, "Robert Anderson" <robander@us.ibm.com> wrote: > I think Kris may be addressing this with her question about which format > are used, but -- does anybody use the contains/by links in the PDF? I > personally use them relatively often, but only in the HTML - apart from > checking that they work, I don't think I've used them in PDF. So, another > idea could be to include them where they are in HTML, but filter them out > in PDF, provided OASIS rules allow for that. > > Robert D Anderson > IBM Authoring Tools Development > Chief Architect, DITA Open Toolkit (http://dita-ot.sourceforge.net/) > > > > From: "Bissantz, Debra" <Debra.Bissantz@lsi.com> > To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org> > Date: 09/12/2012 10:28 > Subject: RE: [dita] DITA 1.3 documentation -- shall we remove the > Contains and "Contains by" tables > Sent by: <dita@lists.oasis-open.org> > > > > I also use the tables to navigate through the spec. I would be disappointed > to see these moved to an appendix. In the HTML version, that would require > additional clicks to get to elements in the content tables. > > I also don't use the PDF version as much as I use the HTML version. It > takes quite a while for the PDF to open. I'm also pretty familiar with the > domains, so I know where to start looking for an element. > > I agree that moving the alphabetical list to the front would be helpful. > > - Deb > > -----Original Message----- > From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On > Behalf Of Noz Urbina > Sent: Wednesday, September 12, 2012 8:18 AM > To: Jang F.M. Graat > Cc: dita > Subject: RE: [dita] DITA 1.3 documentation -- shall we remove the Contains > and "Contains by" tables > > I second that Jang! > > My usual method is: > go to the ToC > do a search for the element I want > use the tables to navigate around > > -----Original Message----- > From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On > Behalf Of Jang F.M. Graat > Sent: 12 September 2012 15:45 > To: DITA TC > Subject: Re: [dita] DITA 1.3 documentation -- shall we remove the Contains > and "Contains by" tables > > 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.h >> tml >> >> 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 > > > --------------------------------------------------------------------- > 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 > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org > For additional commands, e-mail: dita-help@lists.oasis-open.org > > > ______________________________________________________________________ > This email has been scanned by the Symantec Email Security.cloud service. > ______________________________________________________________________
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]