ZedAI Primer Notes
From zedwiki
Contents |
Introduction
Minor point, but my spidey sense tingles when I see statements like “an easily understood introduction”. They tend to become lightning rods for derisive comments from people who don’t easily understand and then want to complain in forums and on lists. Fixed.
Markus: "The intended audience includes developers [...] ". Is this really true? Isn't the intended audience people wanting to learn how to produce documents (marker-uppers?) Fixed.
Examples 1.1, 2.1, etc.
The xmlns attribute has been stripped from the document element in all these examples during processing. Markus: this is my fault - I'll fix.
Section 1.2, etc.
Is there such a term as “the Z39.86-2010 core markup” anymore? Should this be the profile's markup model now?
James: Changed to Z39.86-AI core modules, as this is how the namespace is defined in the spec (section 3.6).
Sections 1.3, 1.5
Referencing of examples should be more consistent. 1.3 contains an example but the para below then talks about declaring the decl prefix in the document element, which is from the example in 1.1. Section 1.5 references back to 1.1 with no embedded example like 1.3 or quick link back to 1.1. Examples should be easily referenced, as no one will have them in memory while reading.
James: I made references to examples into links, except where they are referenced immediately before or after the actual example.
Section 1.3.1
Introduces what an RD is, but relies on a large example alone to explain how documents are constructed. Would be helpful to break the document down and explain in more detail what function the various parts serve (as obvious as they may seem in places). The full example might be better placed in an appendix, as it breaks the flow of the document.
James: I simplified the example to demonstrating just a single reference -- the normative schema. I think that will suffice for the primer.
Section 2.2
"As noted above," A precise reference/link would help. Also, the prose starting from this paragraph would appear to be dated, and at the least is quite confusing (core language requiring modules, etc.).
James: I have rewritten this paragraph to better match the new spec. Please review for accuracy and correct use of terminology.
Section 2.3
Is there a better statement we can make to end this section than minimizing duplicaton of effort? I assume the duplication of effort here must mean not re-inventing the wheel, but my first thought was that it was suggesting that you should try not to have to mark things up twice. Perhaps some remarks about keeping in line with industry standards would help flesh the ending out, too.
James: I just removed that last sentence altogether, since it was really aimed at profile creators, not document creators.
Section 3.2
Being a structure freak, I don't agree that specialized elements would make the schema "too unwieldy to use", but is there a nicer way to phrase this to reflect that the structures are fine as is and that role is only adding refinement to them. It sounds like role is a hack to making proper structures. Fixed.
Section 3.3
"RDF is the technology behind the "semantic web" and is a language for representing information about resources on the World Wide Web."
This statement doesn't say much practical about what RDF is, but is the only statement about it. I think all we need to say is how it's a means of expressing information about elements and the data they contain and move on. Fixed.
Do we need to say anything about Notation3 here? James: I don't think so; that's more of a profile-creator thing.
Section 3.4
The last paragraph of this section doesn't make sense to me -- I think that the example may have been changed but the spec prose didn't follow the change. I'm not sure that I know what was meant here, so I'm leaving this for someone who understands it better to fix.
Section 4.2
The big example is followed by a paragraph that references content that has scrolled out of view. I think the para will prove a confusing set of statements for general readers without the specific context to look at (all the mathml tagging is unimportant to what is being discussed).
James: I like having the example documents be real, complete documents, so I don't want to lose the MathML. I added an extra example of just the head stuff following the technical description so that it's easy to see.
Section 5.1
"The really ambitious metadata providers..." would be better to note the practical purposes that attaching additional metadata records can serve than calling it ambitious. Fixed.
Section 5.2
"By implication, you can only use metadata expression languages that are published as RDF in this way." Disconnect on reading this sentence. I don't think we've said anywhere in the spec that we've done away with @name and that using rdf is your only option on meta (it's only implied, at best, by the fact we talk about it for attaching metadata and inline the few required). Should this be spelled out clearly for people coming from dtbook?
Markus: agree: saying that the "classic html meta element" is no longer available could be a good thing. (Notes that there's also going to be changes to how this is done as we (hopefully) adopt RDFa 1.1 later in the year, as an example the sent quoted above will no longer be entirely true.)
James: I have rewritten this, but please review for accuracy.
Section 6
Should probably be built out into a proper primer.
Markus: agree, note my comment re Introduction above that this doc seems targeted as a primer for marker-uppers, not profile creators. Probably best in this doc to be silent on profile/feature creation; matter for a separate primer.
James: Commented out this whole section.
General Notes
Needs a packaging section.
I think this document could work better as web documentation (whether in a wiki or not). But I generally hate the all-in-one primer concept that requires scrolling up and down to get information so am biased that way.
