Re: Syncing the architecture document and the glossary

* Christopher B Ferris <chrisfer@us.ibm.com> [2003-04-01 10:58-0500]
> A couple of points to consider going forward.
> 
> I think we should be fairly deliberate in proceeding to synchronize
> the two documents.  We might consider that the architecture document
> be the normative source for definitions that could be slurped out
> into the glossary using some form of stylesheet.  That way, we don't
> have to worry about future synchronization issues.

That's indeed a possibility.

But in the end, I think that whether the definitions are in the
architecture document or in a separate one, the main problem is
discipline: define the term in one place and only call it by reference
and not by value everywhere else.

> Secondly, where we have a discrepancy, I think that we should be
> carefully considering which of the two we like best rather than just
> picking one document's definition over the other for all cases.

I completely agree, and this is what I was hinting with my step 2
which was to report the discrepancies between existing definitions,
and then think about why there is a difference and take action.

And this is also why I was saying that step 2 and 3 were likely to
appear after this round of publication because it will not be as easy
as copy-paste.

I think that we agree that we have two sources of information that we
got via two different processes, and that they need to be merged
carefully in order to have something sound and complete.

Regarding where the definitions should live, I am more or less
ambivalent since I see advantages and drawbacks for both solutions.

One way to go forward then could be to just add to the glossary all
the new definitions from architecture document and mark them as such,
and then after the publication start work on reconciliating and maybe
change the way the glossary terms are used and maintained.

Regards,

Hugo

-- 
Hugo Haas - W3C
mailto:hugo@w3.org - http://www.w3.org/People/Hugo/

Received on Tuesday, 1 April 2003 11:52:53 UTC