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

Ian Hickson <ian@hixie.ch>, 2009-01-30 07:49 +0000:

> On Fri, 30 Jan 2009, Michael(tm) Smith wrote:
> > ... 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?
>
> It makes sense to me to have them in for review purposes, yeah.

OK, I will get that note added.

> > 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.

OK, understood. I will make an effort to get us further toward
having the draft more precisely describe what uses it's intended
for. To do that, maybe instead of trying to come up with a perfect
general description of the overall audience as a group, I can add
an itemized list that describes specific cases for which it's
intended to be useful; e.g.:

  You may find this document useful if:

    - You are a developer of a tool that programatically generates
      HTML output, and you need to know the rules for what
      constitutes a conformant document -- so you can help ensure
      that tool produces output to follows those rules.

    - You are a Web author and you need a thorough and
      authoritative reference to descriptions of what each of the
      elements and attributes in the HTML language are meant to
      represent -- so you can make sure that in the documents you
      create, you're using those elements and attributes of the
      language correctly, as they are intended to be used (and not
      abusing them).

    - You are a Web author and you need a reference to which
      elements and attributes are valid in which particular
      contexts in a conformant document -- so that you can help
      ensure your documents don't contain unexpected markup
      errors.

    - You are writing a book or guide to HTML and you need a
      thorough and authoritative reference to the structure and
      semantics of the language -- so that you can ensure the
      descriptions in your book align with those.

> > > * 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.

OK, I see now.

> It also needs a change to the audience statement, since such a
> constraint on the purpose of this draft is not currently clear.

It seems like it would be in line with the needs of the intended
audience if added a statement saying basically the same as what
you just wrote above (that a conformant document can't contain
relative URLs when the base URL can't be used to resolve URLs) and
making a reference to a normative document that actually explains
how relative URLs are resolved.


> 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.)

Understood (though I wouldn't agree that either of the two cases
are an especially accurate description of the purpose of the draft).

> > > 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.

That would be great. In the mean time, I can imagine I might also
get around to making an attempt at putting something together
along those lines (before September).

  --Mike

-- 
Michael(tm) Smith
http://people.w3.org/mike/

Received on Friday, 30 January 2009 09:27:25 UTC