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

Lachlan Hunt <lachlan.hunt@lachy.id.au>, 2008-11-19 19:39 +0100:

>    Regarding the draft of the Markup Spec [1], it is unclear to me who the 
>  intended audience of the document is. [...]
>  While it is clear that the scope is limited to markup producers, there are 
>  still a wide variety of such producers, each with many overlapping and 
>  distinct needs.  In order to review the proposal the proper context, it is 
>  necessary to clearly define who the intended audience is so that it can be 
>  evaluated in regards to whether or not it adequately addresses the needs of 
>  that audience.

I agree that clearly defining somewhere the intended audience for
any spec is in principle potentially quite useful.

But would you say that it's also necessary or useful for the
existing HTML5 draft to have its intended audience clearly defined
somewhere? Or that it also can't be evaluated without such a clear
definition of its intended audience?

I would certainly not want to make the mistake of attempting to
define the intended audience but failing to articulate it broadly
enough or accurately, and so end up prematurely constraining
evaluations about its usefulness.

>  The set of markup producers include authors of various skill levels, 
>  authoring tool vendors (like Dreamweaver), tutorial writers, CMS vendors, a 
>  wide range of other tool vendors who's products provide some form of 
>  automatically generated HTML output.

I would say that all of the above are potentially part of the
intended audience for the document. But I would not say that's
necessarily anywhere close to being a complete list of specific
classes of readers who might find the spec useful.

I think it's also possible to imagine that the editor of a spec
may not be aware of all the specific classes of readers who might
find something useful in a particular spec.

>  Each of those groups requires different kinds of information from different 
>  sections of the spec, depending on their specific needs and abilities.  For 
>  instance, an author who's just writing a blog needs the syntax, semantics 
>  and content models, but needs it in a way that is very reader friendly.

I will concede that a casual author of that sort is not likely to
be relying directly on this document for information, but more
likely instead to rely on an authoring guide defined third-party
reference of some kind (one that is less formal and so very likely
also less rigorous and less precise).

I think it is generally quite difficult to satisfy within the same
specification a requirement for reader friendliness and a
requirement for rigor and precision and unambiguity -- and that
specifications should never sacrifice rigor and precision and risk
ambiguity just in order to attempt to be reader-friendly.

>  Each of those groups requires different kinds of information from different 
>  sections of the spec, depending on their specific needs and abilities.

Or some of then don't need or want a spec at all -- any spec --
but want instead an authoring guide, or a training course, or an
application that enforces the constraints of the spec for them
without them needing to think about the details at all.

>  Whereas an authoring tool vendor would be able to handle a more formal 
>  grammar to explain the conforming syntax, but also very likely needs the 
>  parsing

I would think (hope) that most authoring-tool vendors are not
going to be writing their own HTML5 parsers from scratch, and that
will maybe help free up some time for them to focus instead on
things like building their applications in such a way that they
help authors to produce conformant documents.

I can't see that authoring-tool developers necessarily need to
know or care what the parsing rules are. I can imagine some of
them might rather just not know at all and would prefer a separate
spec that provided just the document-conformance criteria.

I can see that it certainly might be helpful for them or anybody
else to know what the parsing rules are. But it's not clear the
it's necessary for them to know. And my draft is an attempt to
scoping as much as possible down to just the criteria that are
absolutely necessary for producing conformant documents.

Just as a further aside about authoring-tool developers: It would
seem to me that they mainly just want to know to how work
programatically with whatever representation the particular HTML5
parser (or library that incorporates an HTML5 parser) exposes to
them and whatever interfaces for working with that representation
are made available to their application by the programming
language they are using. That representation and those interfaces
may not be based on the DOM at all. So not only do they not
necessarily need to know about the parsing rules, they don't
necessarily need to now about the DOM either.

>  and possibly rendering requirements, in the case of WYSIWYG editors.

I will concede that implementors of WYSIWYG editors would
certainly want to know about rendering requirements. But of course
not all authoring tools are WYSIWYG editors, and I don't think
developers of non-WYSIWYG editors are likely to prefer needing to
go to a spec that also defines rendering requirements just in
order to determine what the document-conformance requirements are.

>  Based on the way the draft is written, it's not clear that the draft 
>  adequately addresses the needs any particular group, nor provides all the 
>  required information.

Whether or not is provides all the required information depends on
what you think all the required information is. This spec is an
attempt at defining only the required information that is
necessary for determining whether a particular serialized instance
of the HTML language is a conformant instance of the language or not.

And for the record, it's not a goal for this spec to also specify
that, say, any embedded/reference Javascript or CSS stylesheet or
XSLT stylesheet associated the document also needs to be
conformant in order for the document itself to be conformant.

>  It also purports to be a normative document, which indicates that it's 
>  supposed to be more than just an informative syntax guide.

Yes, it does currently, though it didn't initially and it's not
outside of the realm of possibility that we could eventually end
up deciding that it should only be informative and not normative.

The main reason I added the text that's in there now that asserts
it's normative was that I want it to be evaluated using the same
expectations for rigor and precision that lack of ambiguity that
readers have (or should have) for the existing HTML5 spec or any
other spec that attempts to be rigorous and precise and
unambiguous. I could see that without some explicit statement in
there making it clear it attempts to be normative, some people
were already describing it as an authoring guide and evaluating in
terms of their expectations for what an authoring guide should be,
and not in terms of what the spec actually attempts to be.

>  This is a 
>  problem because it duplicates and restructures a lot of information from the 
>  spec itself, but not always by copying it verbatim.  Even if it did copy 
>  everything verbatim and elimited the possibility of conflict, I don't 
>  understand why any of it needs to be normatively defined twice.

If we were to move forward with publishing this spec as a
Recommendation-track deliverable, I would expect that ideally it
would be as the single normative definition of what a conformant
HTML document instance is. That is, we would not be normatively
defining anything twice -- whatever we published in this document
would necessarily supersede any definition anywhere else of what a
conformant HTML document instance is.

But I suppose that even if we were not to make it normative, this
document could also have some value as an informative source. And
if we were to decide to publish it as such, the current assertions
within it about it being the normative definition for the language
would need to be changed to make it clear that it's not.

>  Since both would be normative, what would happen in the event of a conflict? 

If it were published as a normative spec, it would necessarily be
the only normative definition of what a conformant document
instance of the HTML language is, so there would be no conflicts.

>  There is also some overlap with the information provided in authoring guide, 
>  such as providing the element content models, describing the syntax, etc.  

I suppose that's an unavoidable overlap. It's not possible for it
to normatively define what a conformant document is without
providing the content models or the syntax rules.

The related material in the authoring guide would ideally not
really be redundant with this spec, but would instead be an
elaboration or amplification or what is in this spec, presented in
a more reader-friendly way than this spec can (being that it is
constrained more by the need to be rigorous and precise and
unambiguous).

>  However, unlike the authoring guide, it's written in what appears to be some 
>  type of formal grammar, which isn't really reader friendly, and seems less 
>  suitable for authors than the way the spec itself is written.

The choice of using a formalisms to define the content models is
not entirely consistent with the approach used in specs defining
other document formats.

That said, I'm not personally wedded to the idea of having only
the formalisms in the spec, nor of the formalisms even necessarily
being the normative definitions.

What I mean is, I think it's quite possible that in whatever spec
(if any) we decide to publish as a separate spec defining what a
conformant document is, the normative definitions of the content
models might be only in prose -- as they are now in the existing
HTML5 draft -- and the document might completely dispense with
having any formalisms at all.

Or it might include both normative prose and informative
formalisms. There's at least one other relevant precedent for
that -- The Atom Syndication Format (RFC 4287):

  http://tools.ietf.org/html/rfc4287/

That spec uses both normative prose and informative formalisms.
And the formalism that the content models in my draft are
expressed in the same formalism (RELAX NG Compact Schema) as what
that spec uses.

  --Mike

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

Received on Thursday, 20 November 2008 13:11:46 UTC