Hiho,
the night was long and without sleep due to some heavy-to-digest pizza,
so I had time to think about a couple of other things we didn't talk
about yesterday. The first two are about Mallard, the third is just a
note about full-text search in Yelp.
===================================
1. Local and global glossaries
===================================
In my (limited and still growing) experience as a technical writer at
work, we always needed to build up a glossary of terms both for a single
document and shared across a set of guides. This is an essential part of
every user documentation.
For example, in the GNOME scenario, we'd need to define "Network bridge"
or "Gateway" because some applications would use it in their help, but
without a glossary it would be difficult to find the first occurrence
where the term is explained inline.
However, some terms can have different meanings depending on the
context. In that case there are mainly two ways to differentiate about
them:
* Provide a longer name which retains context information (e.g. "network
bridge" and "bridge [construction]"). Wikipedia uses disambiguation much
like this.
* Use the most common name globally, and override it for the local
document if needed.
I suggest using both. How does this fit in Mallard?
My proposal is the following:
* Add a "lookup" element with the following attributes:
* @href --> glossary item to lookup.
If not specified is set to CDATA
* @scope --> local|global literal.
If not specified, tries first searching
locally, then falls back globally.
* Allow the glossary page to have a "glossary" element, in which a list
of "term" elements occurs. These need an optional "@sortname" attribute,
so that we can specify that e.g. "network bridge" has to be sorted as
"bridge, network" and thus goes under the "B" letter.
* A glossary page can then exist for each project, and a global glossary
for the whole of GNOME can be maintained within the user guide. Else,
the @scope attribute could be more general and allow for more
granularity, by specifying the level on a tree where search has to be
performed (Shaun? any ideas?)
* The glossary terms would then be retrieved via AJAX, and displayed in
a tooltip/in a new <div> with a mouse over event (accessibility folks,
is that okay?). On click event, the whole glossary can be shown, jumping
to the right term.
So what do you think?
=======================================
2. Explicit keywords to help search
=======================================
This is not so crazy as it seems, and would help reduce "false
positives" allowing for better sorting search results. After all, also
Google does that (the META keywords element, to say one way to achieve
this).
The proposal is to add an optional "@keywords" comma-separated list
attribute to the "section" element. Terms appearing in this list would
be assigned an high score when performing the search. If a writer uses
them, they could be a great helper, and ameliorate the crappy-searches
current situation.
==========================================
3. Why we still need full-text search
==========================================
Just a couple of other example on why full-text search is needed.
a) Users, especially n00bs, make mistakes. Google knows that and even
suggests you some corrections with the "did you mean...?" section.
b) Last evening/morning (depending on where you live ;-)) we talked
about how Italian has different male-female and singular-plural forms.
For verbs, matters gets far worse. But Italian still plays nice. Take
Polish, for example... http://en.wikibooks.org/wiki/Polish/Plural
c) Users may search for the same thing in different ways, even in
English. For example, I'd search for "network configuration", but
another user may look for "configure network" and another one for "how
to configure your network". The last one, typed in my version of yelp,
brings up a document about gdmsetup as the first item, a totem page as
the second and the Ubuntu server guide as the third. Then a long list of
pages containing "click-to-focus" is shown, since they contain the "to"
word. Wtf?
(By the way, clicking on a item shown here, crashes Yelp 2.26, but
that's an entirely different problem).
So, any other ideas?
Matteo
Attachment:
signature.asc
Description: Questa =?ISO-8859-1?Q?=E8?= una parte del messaggio firmata digitalmente