It's a tricky situation. The tables
contain useful information, but if readers cannot find the
relevant topic, they never will see that useful information.
In an ideal world, we'd have:
- Some way of instructing PDF viewers and Web browser to not
include the content of those tables in the search results
- The time and resources to carefully and properly add index
entries to the source files.
In the absence of an ideal world, let's see what tactics we can
come up with to improve readers' ability to find information in
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/11/2012 5:51 PM, Scott Hudson wrote:
Hm. I disagree. One of the most
powerful benefits of these tables is being able to see where
an element is valid and what it contains. If you remove these,
the element reference will be useless.
--Scott
On 9/11/12 3:48 PM, "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 <http://www.eberleinconsulting.com>
+1 919 682-2290; kriseberlein (skype)
On 9/11/2012 5:33 PM, Scott Hudson wrote:
Re: [dita] DITA 1.3
documentation -- shall we remove the Contains and
"Contains by" tables 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>
<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>
<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.
______________________________________________________________________
______________________________________________________________________
This email has been scanned by the Symantec Email
Security.cloud service.
______________________________________________________________________
|