Re: Who is the Intended Audience of the Markup Spec Proposal?

On Fri, 30 Jan 2009, Michael(tm) Smith wrote:
> > 
> > Assuming the above audience statement, I have the following review 
> > comments:
> > 
> > * I don't think we need to include the obsolete elements, since they're 
> >   not needed for conformance (by definition).
> 
> I agree that they are not needed for conformance. However, I think it's 
> useful to keep them in there at this stage in the life of the document, 
> in part to help make readers aware of just which elements are obsoleted 
> (or have been proposed to be obsoleted). I do think that no elements 
> that we agree are obsoleted should be included in an LC draft or 
> anything beyond that.
> 
> Anyway, I did go ahead and raise bug 6501 for this. If I add a comment 
> to the Status section or another part of the doc stating that no 
> obsoleted elements will be included in any draft we may publish at LC or 
> beyond, would you be OK with that? If so, I'll do that and close out the 
> bug. If not, I'll keep it open and encourage people who want to comment 
> on it to do so there.

It makes sense to me to have them in for review purposes, yeah.


> > * I don't think we should include <canvas>, since just saying the element 
> >   exists doesn't really help authors without its API.
> 
> I raised bug 6502 for that. I don't agree with you rationale on this. 
> For a document that restricts its purpose do describing what a 
> conformant document is and describing what each of the elements in the 
> language represent, omitting <canvas> would seem to me to be a bug. The 
> document is explicitly not scoped to actually also describe the behavior 
> of <canvas> and/or how to actually use it in a Web application -- but 
> instead just to describe what <canvas> and its accompanying attributes 
> represent.

This gets down to the heart of the issue with respect to the audience 
statement -- if the audience is authors in general, as the draft currently 
says [1], then <canvas> is really only useful with its API. If the 
audience is just people who want to take a byte stream and be able to have 
a quick reference that says whether or not it is conforming, so that they 
don't have to read the whole spec, then the API isn't needed.

A lot of your comments here and below (I didn't reply to all of them) 
suggest that the audience you have in mind isn't quite the audience you've 
described, which makes it difficult to properly review the draft. I 
understand that you don't like discussing the audience, but this confusion 
really does make it harder to review the draft, since one doesn't always 
know whether a missing section is intentionally missing or not, etc.

[1] (Well, it says "producers of documents intended to conform to the 
requirements it describes", and defines "producers" as "HTML authors (that 
is, people) and applications (such as editors and content management 
systems) that produce HTML content". But since the whole point of having 
authoring requirements is that we want all authors to conform to the 
requirements, my reading of this is no different than if the draft just 
said "authors". If something more specific is meant -- well, see above.)


> > * The spec doesn't define for authors how relative URLs are resolved.
> 
> (bug 6505) Is it necessary for it do so? That is, if the purpose of this 
> spec remains constrained to describing what a conformant document is and 
> what the elements and attributes are meant to represent, would it need 
> to describe how relative URLs are resolved?

If the purpose of this draft is constrained to describing what a 
conformant document is, then it needs enough material in there to make 
sure that the reader can check that the document doesn't contain relative 
URLs when the base URL can't be used to resolve URLs. It also needs a 
change to the audience statement, since such a constraint on the purpose 
of this draft is not current clear.

If the purpose of this draft is to help authors who like formalisms in 
their documentation to write HTML files, then it needs to give them 
information on how the base URL mechanism works in enough detail that they 
can understand the feature.

If the purpose of this draft is just to give readers information on the 
elements and attributes and not actually give them detailed information on 
the full implications of those same, then how relative URLs are resolved 
is probably information that can be omitted.

(In either of the last two cases, I also think it would be a mistake to 
make the draft normative.)


> > I think it would be helpful to also include the element-specific APIs, 
> > so that authors don't have to go to yet another reference for those.
> 
> [...] So I'll try to get them into the draft in some form, and after I 
> do, we can take a look at it and see if they work OK in that context.

For what it's worth, I intend to write text that would be somewhat useful 
for you here at some point in the coming months (probably in September). 
The current text in the HTML5 spec about the APIs is completely focused on 
the implementation aspects and really is lacking useful introductory 
statements for authors, which is presumably what you'd want here. As part 
of making the "author view" for the HTML5 spec, I expect to have to write 
text for a lot of the APIs.


> I would also very much appreciate more feedback from you once I get the 
> document further along.

That would be my pleasure.

Cheers,
-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'

Received on Friday, 30 January 2009 07:50:12 UTC