Creating a DocBook glossary in a distributed documentation production environment

[Karen Schneider-2]

This is half a DocBook question and half a "process" question for
anyone on this list working in a distributed DocBook production
environment where for a particular assembled document you are
generating at least one common glossary. (In this case, the assembled
document is planned as a set with two books, multiple chapters within
each book, and sections within each chapter.) Authors will be working
on chapters and sections independently of one another.

I am trying to figure out the logistics of having authors generate
glossterms/glossentries that are unique and consistently-formed and
contribute to a common glossary. It may well be that this isn't
possible, or that it is best done as a sort of kludge, where they mark
up glossterms and then submit the full glossary entries in a separate
document, for editors to manually integrate this content into a main
glossary after human review. Either that, or authors ignore glossary
creation altogether and the next tier of editors is responsible for
glossary creation.

I have read through the instructions for glossary databases in
Stayton's guide, thought about manual vs. automated creation, etc. but
am still stuck at the "process" level of all this.

--
--
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| kgs@...
| Web: http://www.esilibrary.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Richard Hamilton-2]

Karen,

For a simple distributed DocBook production environment, I'd
suggest a Subversion repository that all authors use for their
individual parts, as well as shared parts (like the glossary).

I'd use a glossary database (Chapter 17 of Bob's book) that is
writable by any author. Authors can populate it with whatever
terms they like, using a simple rule for id disambiguation (I
use gloss.term, where gloss is constant and term is the term
itself. If you need to disambiguate two forms of the same term,
you can add something at the end.)

If two authors need to use the same term, they will need to
discuss whether they can create one entry for both uses, or
if they need separate entries, but beyond that, there's not
much need for coordination.

The build process described in Bob's book buildsa glossary for
each document based on the terms used in that document. Simple
and automated.

Hope that helps.
Dick Hamilton
---------------------------------
XML Press
XML for Technical Communicators
http://xmlpress.net
[phone]

> -----Original Message-----
> From: Karen Schneider [mailto:kgschneider@...]
> Sent: Monday, September 07, 2009 12:11 PM
> To: docbook-apps
> Subject: [docbook-apps] Creating a DocBook glossary in a
> distributed documentation production environment
>
>
> This is half a DocBook question and half a "process" question for
> anyone on this list working in a distributed DocBook production
> environment where for a particular assembled document you are
> generating at least one common glossary. (In this case, the assembled
> document is planned as a set with two books, multiple chapters within
> each book, and sections within each chapter.) Authors will be working
> on chapters and sections independently of one another.
>
> I am trying to figure out the logistics of having authors generate
> glossterms/glossentries that are unique and consistently-formed and
> contribute to a common glossary. It may well be that this isn't
> possible, or that it is best done as a sort of kludge, where they mark
> up glossterms and then submit the full glossary entries in a separate
> document, for editors to manually integrate this content into a main
> glossary after human review. Either that, or authors ignore glossary
> creation altogether and the next tier of editors is responsible for
> glossary creation.
>
> I have read through the instructions for glossary databases in
> Stayton's guide, thought about manual vs. automated creation, etc. but
> am still stuck at the "process" level of all this.
>
> --
> --
> | Karen G. Schneider
> | Community Librarian
> | Equinox Software Inc. "The Evergreen Experts"
> | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
> | kgs@...
> | Web: http://www.esilibrary.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@...
> For additional commands, e-mail:
> docbook-apps-help@...
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Karen Schneider-2]

Dick, this would at least be a good start (for the glossary). I had
looked at 17 but was still mulling process and workflow. What you
write makes sense. On the Subversion repository we're going to do
something very similar to that. I like the gloss.term idea, and a
public repository, which we are already using, gives the authors an
easy place to look to see if a term has already been added.

From previous editorial experience, I will state in the guide that
there will be one entry per term. Editors will break ties, enrich
definitions, etc. Any other way lies madness ;-)

Karen

On Mon, Sep 7, 2009 at 5:57 PM, Dick Hamilton<rlhamilton@...> wrote:

> Karen,
>
> For a simple distributed DocBook production environment, I'd
> suggest a Subversion repository that all authors use for their
> individual parts, as well as shared parts (like the glossary).
>
> I'd use a glossary database (Chapter 17 of Bob's book) that is
> writable by any author. Authors can populate it with whatever
> terms they like, using a simple rule for id disambiguation (I
> use gloss.term, where gloss is constant and term is the term
> itself. If you need to disambiguate two forms of the same term,
> you can add something at the end.)
>
> If two authors need to use the same term, they will need to
> discuss whether they can create one entry for both uses, or
> if they need separate entries, but beyond that, there's not
> much need for coordination.
>
> The build process described in Bob's book buildsa glossary for
> each document based on the terms used in that document. Simple
> and automated.
>
> Hope that helps.
> Dick Hamilton
> ---------------------------------
> XML Press
> XML for Technical Communicators
> http://xmlpress.net
> [phone]
>
>
>> -----Original Message-----
>> From: Karen Schneider [mailto:kgschneider@...]
>> Sent: Monday, September 07, 2009 12:11 PM
>> To: docbook-apps
>> Subject: [docbook-apps] Creating a DocBook glossary in a
>> distributed documentation production environment
>>
>>
>> This is half a DocBook question and half a "process" question for
>> anyone on this list working in a distributed DocBook production
>> environment where for a particular assembled document you are
>> generating at least one common glossary. (In this case, the assembled
>> document is planned as a set with two books, multiple chapters within
>> each book, and sections within each chapter.) Authors will be working
>> on chapters and sections independently of one another.
>>
>> I am trying to figure out the logistics of having authors generate
>> glossterms/glossentries that are unique and consistently-formed and
>> contribute to a common glossary. It may well be that this isn't
>> possible, or that it is best done as a sort of kludge, where they mark
>> up glossterms and then submit the full glossary entries in a separate
>> document, for editors to manually integrate this content into a main
>> glossary after human review. Either that, or authors ignore glossary
>> creation altogether and the next tier of editors is responsible for
>> glossary creation.
>>
>> I have read through the instructions for glossary databases in
>> Stayton's guide, thought about manual vs. automated creation, etc. but
>> am still stuck at the "process" level of all this.
>>
>> --
>> --
>> | Karen G. Schneider
>> | Community Librarian
>> | Equinox Software Inc. "The Evergreen Experts"
>> | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
>> | kgs@...
>> | Web: http://www.esilibrary.com
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docbook-apps-unsubscribe@...
>> For additional commands, e-mail:
>> docbook-apps-help@...
>>
>>
>
>
>

--
--
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| kgs@...
| Web: http://www.esilibrary.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...