OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[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


Title: Re: [dita] DITA 1.3 documentation -- shall we remove the Contains and "Contains by" tables
Hi, Mark.

Believe me, the content in the Contains and "Contains by" tables was auto-generated; there is NO way that we would do that sort of work by hand :)

Robert Anderson did that work; I'll defer to him for details.



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 8:48 AM, Mark Poston wrote:
Hi,

I wonder if an auto generated form of the documentation would be suitable for the contains/contained by information, generated from the schemas.

I am thinking specifically of features such as oXygenXML's schema documentation tool that could allow us to create a DITA-based output for a schema – given an XSL is developed. Currently they support HTML/DocBook/PDF.

The standard output may be deemed too technical for our requirements but a cut down simplified version could be created with relative ease.

Kind regards

Mark Poston – Senior Technical Consultant
Mekon Ltd.
tel +44 20 8722 8461 | mob +44 7515 906032 | Skype mark_mekon.com

On 11 Sep 2012, at 22:50, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

Yes, the links work fine. It just is very difficult for someone to *find* topics in the spec, and I think we need to address this for DITA 1.3.

Removing the "Contains" and "Contains by" tables -- perhaps having them in a secondary document -- would be one way to improve readers' ability to search the spec and find mentions of particular elements.


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/11/2012 5:33 PM, Scott Hudson wrote:
You are saying that the false hits are in the search only, right? When I view the HTML version of the spec, the contains/contained by links work just fine.

I don’t have any solution to the search problem.

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/11/12 3:01 PM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote:

  
What is your suggestion for fixing the false hits?
 
 

Best,
 Kris
 
 Kristen James Eberlein
 Principal consultant, Eberlein Consulting
 Co-chair, OASIS DITA Technical Committee
 Charter member, OASIS DITA Adoption Committee
 www.eberleinconsulting.com <http://www.eberleinconsulting.com>
 +1 919 682-2290; kriseberlein (skype)
 
 
 On 9/11/2012 4:56 PM, Scott Hudson wrote:
 
 
Re: [dita] DITA 1.3 documentation -- shall we remove the Contains and "Contains by" tables I think it’s useful. Let’s fix the false hits problem so it works. I use this feature all the time.
 
 Thanks and best regards,
 
 --Scott
 
Scott Hudson | Pelco by Schneider Electric | United States | Standards Lead
 Phone:
+1-970-282-1952  | Mobile: +1-720-663-7268 | Support: +1-800-289-9100
 Email: scott.hudson@schneider-electric.com | Site: pdn.pelco.com | Address: 3800 Automation Way, Suite 300 Ft. Collins, CO 80525-3449 - USA
 

 
 
 On 9/11/12 2:49 PM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote:
 
 

  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 <http://www.eberleinconsulting.com>  <http://www.eberleinconsulting.com>  
  +1 919 682-2290; kriseberlein (skype)

______________________________________________________________________
 This email has been scanned by the Symantec Email Security.cloud service.
______________________________________________________________________
 
 


 
______________________________________________________________________
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]