Indexing question

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Indexing question

C-29
This is just a general question about indexing.  I am working on a
large document that is being ported over to Wiki format.  One of the
printed doc features that has fallen off with the port to Wiki is the
index.

In traditional documentation, a good index was important.  As we move
more and more away from traditional doc techniques and go to web based
docs we rely on search engines to fill the gap where indexes and index
tagging (in traditional tools like Framemaker) are missing.

How important are people finding the index in newer doc methods?  What
can be done to fill that missing indexes for online docs?  Especially
for online docs (such as Wiki) that can be converted to PDF to deliver
a traditional book for people who prefer to read off line?

C.
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Indexing question

Rebecca Walter
On Tuesday 19 June 2007 10:04, Clayton wrote:

> This is just a general question about indexing.  I am working on a
> large document that is being ported over to Wiki format.  One of the
> printed doc features that has fallen off with the port to Wiki is the
> index.
>
> In traditional documentation, a good index was important.  As we move
> more and more away from traditional doc techniques and go to web based
> docs we rely on search engines to fill the gap where indexes and index
> tagging (in traditional tools like Framemaker) are missing.
>
> How important are people finding the index in newer doc methods?  What
> can be done to fill that missing indexes for online docs?  Especially
> for online docs (such as Wiki) that can be converted to PDF to deliver
> a traditional book for people who prefer to read off line?
>

I'm the index obsessed doku-wichtl.  The lack of indexing drives me crazy.  
Searching turns up every reference to a word, but doesn't focus on what is
important.  This is why we use XML for our docs so our PDFs can still have
indexes.

I still have a dream of somehow making a compiled index for our product
manuals so you could look one place and find the info that shows up in any
book, but that has extra challenges in term selection.

However, the Novell documentation team skips indexing, considering it
unnecessary for online docs.

So opinions differ.  If you believe in indexing, you try to index properly and
use a format that supports it.  If you don't, you don't bother even if you
use a format that supports it.
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Indexing question

Thomas Schraitle-2
In reply to this post by C-29
Hi Clayton,

On Tuesday, 19. June 2007 10:04:19 Clayton wrote:
> [...]
>
> In traditional documentation, a good index was important.

I still consider this important, so probably Rebecca is not the only one
obsessed by indices. ;) Really good documentation do not just have an
index, they create terms what are useful for the readers.


> As we move
> more and more away from traditional doc techniques and go to web based
> docs we rely on search engines to fill the gap where indexes and index
> tagging (in traditional tools like Framemaker) are missing.

Yes, and that's sometimes really a pity. In short texts, an index isn't
really necessary. However, in larger documentation, a good index is a
benefit for the reader.


> How important are people finding the index in newer doc methods?  What
> can be done to fill that missing indexes for online docs?  Especially
> for online docs (such as Wiki) that can be converted to PDF to deliver
> a traditional book for people who prefer to read off line?

I can only speak for myself and for LfL: If you create an indexterm in
one of our DocBook sources, it will create an index both in online and
print formats.

However, apart from the technical side, I consider a really good index
still as a kind of an "art". In a project like LfL we haven't defined
indexing yet.
In book production, indices are created at the very end, and I think LfL
makes no exception to that. Many publishers let one person create the
index to have a consistent wording. From my perspective, I don't think
it makes sense to work on index on LfL now. Nevertheless, if we (as a
community) think LfL has reached some "stable" grounds we can implement
indexing.

So these are just some random thoughts.


Best wishes,
Tom

--
Thomas Schraitle

----------------------------------------------------------------------
SUSE LINUX GmbH      >o)   Documentation Specialist
Maxfeldstrasse 5     /\\  
90409 Nuernberg     _\_v   http://en.opensuse.org/Documentation_Team
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Indexing question

C-29
In reply to this post by Rebecca Walter
> I'm the index obsessed doku-wichtl.  The lack of indexing drives me crazy.
> Searching turns up every reference to a word, but doesn't focus on what is
> important.  This is why we use XML for our docs so our PDFs can still have
> indexes.

I agree... search tools work, but then you have to wade through
hundreds or even thousands of irrelevant hits to find the 2 that
apply.  That's where good indexing really shines.

>I can only speak for myself and for LfL: If you create an indexterm in
> one of our DocBook sources, it will create an index both in online and
> print formats.

That works great when you're dealing with DocBook or other XML source
material where you have the ability to add index tags where you think
is important.

I'm trying to experiment and implement other methods of collecting and
producing books - basically trying new approaches to traditional doc
methods.  One I'm working on right now is Wiki.  I know, Wiki is a
collaborative tool, not a doc tool... but I'm experimenting and trying
to look for other ways to encourage community involvement in
documentation.  Right now, the sources I work with are in a custom XML
format that has a very high entry threshold.  Wiki was requested as
the lowest common denominator... so I'm working on that now.  This
means adding in new functionality etc to the Wiki to even have a hope
of making it work... and I'm trying to cover all angles of traditional
doc functionality in teh process.  Thus the question about indexes.
:-)

I'll have a think about your comments here... maybe I'll have a
brainwave today :-)  One can hope... right?


C.
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]