[tei-council] ODD manual

[Julia Flanders]

I really enjoyed reading this document (!?!). I agree, it will 
benefit from being made even more accessible, and from explaining 
things in a bit more detail. But overall I think it's a really good 
start.

A few points for revision which you may already have noted:

--move the explanation of the mode= attribute on <elementSpec> to 
precede the discussion of adding a new element, since that example 
uses the mode= attribute; might even want to have a little section 
heading there like "modifications to the schema" or whatever, with a 
topic sentence like "You can add, replace, remove, or change elements 
using the mode= attribute on <elementSpec>..."

--I think you need to briefly describe the nature, usage, and 
implications of the tei class system at some point fairly early on, 
or at least mention that it exists and point the reader to the 
appendix. (And even in that case, the appendix in its current form 
doesn't discuss any issues surrounding the use of classes--for 
instance, making sure the novice knows that an element may belong to 
more than one class, or that the classes have no relation to the 
modules. So some more extended discussion of how it all works would 
be great.) I first noticed the need in section 4 (Writing ODD 
specifications) in the example of adding a new element, where it 
points out that you can specify what class(es) the new element will 
be added to. By the time we get to the example of adding the <death> 
element the need is more acute. For instance, when reading through 
the example, I find myself wondering what the implications of 
including an element in a particular class are: does it mean that it 
gets to use certain attributes? can one add an element to any class 
at will or is there a possibility of producing something that is 
self-contradictory at a technical level (that is, it's not just 
silly--it doesn't work). I don't think (anticipating a possible 
objection) that the class system needs to be presented in huge detail 
to bog the reader down, just a brief explanation to anticipate these 
kinds of questions, with a pointer to some more complete account 
elsewhere.

--I was glad to see the sentence (after that example) "There is no 
need to specify a module for the element to appear in, as this would 
not be used for anything." and in fact I thought it could have been 
stated even earlier, after that first <soundClip> example (that was 
where the question occurred to me). Perhaps this sentence could be 
placed together with "For objects which are not new, you should 
specify the module in which it was originally defined" right near the 
beginning of the section on modifications. At the moment, 
instructions like these are scattered through as comments on 
examples, rather than being given together as a set of principles--I 
wonder whether the latter might be a useful approach (perhaps with 
reminders as glosses/commentary on specific examples).

--the <include> example takes several readings to grasp; I think it's 
confusing partly because it's sort of a meta-example, and this isn't 
made absolutely clear in the prose. (I even misread "This 
document..." as meaning "the document you're about to see in the next 
example" rather than "the document you're reading", and I think that 
it could also be made much clearer that the <include> element is not 
a TEI element. Possible rewrite for that sentence: "The document you 
are now reading, for instance, pulls in tables created by automatic 
processes using a non-TEI element <include>:
[example]
This <include> element needs to be able to appear almost everywhere, 
so we want to add it to a TEI class whose members are permitted 
almost everywhere; tei.Incl does this job nicely."

--Appendix C, TEI Macros needs more explanatory prose, and also needs 
to make clearer what the stuff in the green boxes is. This section is 
more or less opaque to a novice.

At whatever point in the revision process you think it would be 
useful, I'd be glad to send a list of things that need clarification 
for a more novice reader (i.e. if you want to do the revisions you 
suggest first, I could do a pass on the results).

Best wishes, Julia

At 1:58 PM +0100 5/6/05, Lou Burnard wrote:
>I have now found time to unpack some of the goodies Sebastian has 
>been despatching from the other side of the world. One is a 
>preliminary draft for a "TEI Customization Handbook" which aims to 
>set out all you need in order to adapt the TEI for your own needs. 
>He intended to distribute this to the Council before the Paris 
>meeting, but the PDF file he sent was stripped by the listserv in 
>virginia, and I was too preoccupied with other things to do anything 
>about sending out an alternative.
>
>Anyway, please visit http://www.tei-c.org/ODD/Manual/ now to see the 
>draft in question.
>
>I think the doc is a good start but needs quite a bit more work. The 
>tone is closer to that of TD , the reference chapter of P5 (which it 
>overlaps somewhat) than of -- say -- the TEI Lite tutorial: I feel 
>that it needs to be chattier and more accessible, with plenty of 
>simpler examples before hitting people with e.g. xinclude. Above 
>all, it should take a more "cookbook" style approach e.g. in 
>presenting Roma.  I think the order of presentation is wrong: dtd 
>and relaxng wrappers should be relegated to an appendix.  The lists 
>of classes currently in the appendix are necessary, but probably 
>should be referenced from here, not included in the document, as we 
>will soon have far too many such lists to cope with.
>
>But I think the coverage is right: do Council members have 
>suggestions for other topics they think such a document really must 
>address, bearing in mind the distinction we made at the Paris 
>meeting between
>(a) reference documentation in the P5 Guidelines (TD, CF)
>(b) tutorial introductions (this document)
>
>Lou
>_______________________________________________
>tei-council mailing list
>tei-council at lists.village.Virginia.EDU
>http://lists.village.Virginia.EDU/mailman/listinfo/tei-council