Suggestions regarding creation of an "Authoring Specification" for HTML 5

[noah_mendelsohn]

Ian:  at breakfast this morning we discussed some ideas regarding the
creation of an authoring specification for HTML 5, and you encouraged me
to remind you of some of my suggestions with a note to the comments list.
Here 'tis.

My overall comment is that I think the specification for the authoring of
correct HTML 5 documents is of great importance.  I understand that you
are hoping that the need can be met in part by, eventually, using scripts
to produce a stripped down version of the existing draft, leaving out much
of the parsing and error recovery detail.  Perhaps this will lead to a
first class result, but I have some nervousness that the result might not
be as effective as one might like.  Accordingly, I'd like to suggest that
the following be considered:

* Simple success criteria should be explicitly set down for the authoring
specification.  What information must it convey, to which audiences should
it be comprehensible, etc.?  I'm not suggesting any big, elaborate, or
time-consuming requirements effort, just a very brief set of criteria that
could be agreed by the community as a yardstick for judging any particular
draft.   Perhaps this already exists.
* I think it would be a good idea to generate representative drafts sooner
rather than later.  If practical, this could be done by marking up the
existing draft and running the full automated process.  If that's
impractical soon, as I suspect may be the case, I would think that one or
two members of the HTML working group could be tasked with manually
producing a partial skeleton for evaluation, including at least some of
the key sections such as 8.1, and representative slices of some of the
others.  For example,  if one or two microsyntaxes and the definitions of
a few representative elements were converted, it would probably give a
very good idea as to whether the presentation of all of them would
eventually be effective.  I think the resulting draft should be circulated
for comment, and should be used to inform planning for how the final HTML
5 authoring draft will eventually be prepared.

* I think there are good reasons why most of the semantics of HTML 5 are
explained in terms of the DOM, but it's worth keeping in mind that for
authors (except when scripting), it's the serialized document that's of
primary concern.  So, it's worth explaining clearly and early the key
invariants of what a legal HTML 5 document looks like.  For example:
"Start tags look like <this>, end tags look like </this>; elements are
properly nested and thus encode a tree, which by the way is isomorphic to
the corresponding DOM tree; etc..   Determining thinks like this from the
existing specification is a bit of a theorem proving exercise:  you have
to notice that the DOM is always a tree, even though browsers accept input
that's poorly nested, you have to notice that there are serialization
rules that invariably result in properly nested tags, and you have realize
that those in turn define what is intented as legal HTML 5.  There's a
risk that, if all one does is to strip the existing spec. to produce the
authoring spec, these key aspects of correct HTML 5 will be unduly hard to
discover.

* I think the authoring specification is important enough that attention
should be given to introductory material, organization of the table of
contents, etc.  Perhaps this comment is obvious, in which case I apologize
for mentioning it.  Right now, I understand that the most critical section
for authors is in section 8.1, so it's not immediately obvious that a
simple stripping of the existing draft will result in a document that
flows in sensible order, with key concepts suitably highlighted.  For
example, I could imagine introductory material setting out some of the
information mentioned in the bullet above.  You could also any general
syntactic rules, such as whether tags need to be explicitly closed or can
be implicitly closed by the end tag for a parent, and if it's not obvious
from the table of contents, provide simple guidance as to which sections
are good starting points for learning key concepts.

I hope these suggestions are helpful.   I should point out that they
represent my personal suggestions, and not necessarily those of other W3C
TAG members. Thank you.

Noah



--------------------------------------
Noah Mendelsohn
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------

[Lachlan Hunt]

noah_mendelsohn@... wrote:
> Ian:  at breakfast this morning we discussed some ideas regarding the
> creation of an authoring specification for HTML 5, and you encouraged me
> to remind you of some of my suggestions with a note to the comments list.
> Here 'tis.

In case you're unaware, I'm the editor of The Web Developer's Guide to
HTML 5 [1].  It's intended to be an in depth authoring guide that will
cover everything authors need to know.  However, rather than having it
written  using conformance criteria like the spec uses, it's being
written in much more reader friendly language, as it is inteded for
people who probably aren't too good at reading specs.

I'm also at TPAC this week, so if you like, you can track me down and we
can discuss some things about it if you like.

[1] http://dev.w3.org/html5/html-author/

--
Lachlan Hunt - Opera Software
http://lachy.id.au/
http://www.opera.com/

[Ian Hickson]

On Mon, 20 Oct 2008 noah_mendelsohn@... wrote:
>
> My overall comment is that I think the specification for the authoring
> of correct HTML 5 documents is of great importance.  I understand that
> you are hoping that the need can be met in part by, eventually, using
> scripts to produce a stripped down version of the existing draft,
> leaving out much of the parsing and error recovery detail.  Perhaps this
> will lead to a first class result, but I have some nervousness that the
> result might not be as effective as one might like.

I have now made the three versions available:

   http://www.whatwg.org/specs/web-apps/current-work/multipage/?style=complete
   http://www.whatwg.org/specs/web-apps/current-work/multipage/?style=author
   http://www.whatwg.org/specs/web-apps/current-work/multipage/?style=highlight

They are also available on the W3C space as a single document that you can
dynamically change the view for using your browser's alternative style
sheet interface:

   http://dev.w3.org/html5/spec/


> * Simple success criteria should be explicitly set down for the
> authoring specification.  What information must it convey, to which
> audiences should it be comprehensible, etc.?  I'm not suggesting any
> big, elaborate, or time-consuming requirements effort, just a very brief
> set of criteria that could be agreed by the community as a yardstick for
> judging any particular draft.  Perhaps this already exists.

I've tried to clarify the expected audience here:

   http://www.whatwg.org/specs/web-apps/current-work/multipage/introduction.html#audience

Is that what you had in mind?

> * I think it would be a good idea to generate representative drafts
> sooner rather than later.  If practical, this could be done by marking
> up the existing draft and running the full automated process.  If that's
> impractical soon, as I suspect may be the case, I would think that one
> or two members of the HTML working group could be tasked with manually
> producing a partial skeleton for evaluation, including at least some of
> the key sections such as 8.1, and representative slices of some of the
> others.  For example, if one or two microsyntaxes and the definitions of
> a few representative elements were converted, it would probably give a
> very good idea as to whether the presentation of all of them would
> eventually be effective.  I think the resulting draft should be
> circulated for comment, and should be used to inform planning for how
> the final HTML 5 authoring draft will eventually be prepared.

Doing the whole draft did not end up taking much work (just a couple of
weeks), so I just did the whole thing.

> * I think there are good reasons why most of the semantics of HTML 5 are
> explained in terms of the DOM, but it's worth keeping in mind that for
> authors (except when scripting), it's the serialized document that's of
> primary concern.  So, it's worth explaining clearly and early the key
> invariants of what a legal HTML 5 document looks like.  For example:
> "Start tags look like <this>, end tags look like </this>; elements are
> properly nested and thus encode a tree, which by the way is isomorphic
> to the corresponding DOM tree"; etc..
> Determining thinks like this from the existing specification is a bit of
> a theorem proving exercise:  you have to notice that the DOM is always a
> tree, even though browsers accept input that's poorly nested, you have
> to notice that there are serialization rules that invariably result in
> properly nested tags, and you have realize that those in turn define
> what is intented as legal HTML 5.  There's a risk that, if all one does
> is to strip the existing spec. to produce the authoring spec, these key
> aspects of correct HTML 5 will be unduly hard to discover.

I've tried to write a section that covers these basic points:

   http://www.whatwg.org/specs/web-apps/current-work/multipage/introduction.html#a-quick-introduction-to-html


> * I think the authoring specification is important enough that attention
> should be given to introductory material, organization of the table of
> contents, etc.  Perhaps this comment is obvious, in which case I
> apologize for mentioning it.  Right now, I understand that the most
> critical section for authors is in section 8.1, so it's not immediately
> obvious that a simple stripping of the existing draft will result in a
> document that flows in sensible order, with key concepts suitably
> highlighted.

I don't think the syntax section is actually any more important for
authors than the semantics section, to be honest. There's not really much
point learning how to write until you have a vocabulary to write.

However, I've made the section mentioned above ("A quick introduction to
HTML") link to the syntax section, so for those who find this information
important there will now be a direct reference from the introduction
section to the syntax section.


> For example, I could imagine introductory material setting out some of
> the information mentioned in the bullet above.

I have attempted to do this.


> You could also any general syntactic rules, such as whether tags need to
> be explicitly closed or can be implicitly closed by the end tag for a
> parent, and if it's not obvious from the table of contents, provide
> simple guidance as to which sections are good starting points for
> learning key concepts.

I've tried to do this (in particular I've now included an explicit mention
of the rule that mis-nested tags aren't allowed).


> I hope these suggestions are helpful.

Very much so! Thank you very much. Please let me know if the changes I
have made are satisfactory, or if there is anything else I can do to
improve the specification.

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

[noah_mendelsohn]

Ian Hickson wrote:

> On Mon, 20 Oct 2008 noah_mendelsohn@... wrote:
> >
> > My overall comment is that I think the specification for the authoring

> > of correct HTML 5 documents is of great importance.  I understand that

> > you are hoping that the need can be met in part by, eventually, using
> > scripts to produce a stripped down version of the existing draft,
> > leaving out much of the parsing and error recovery detail.  Perhaps
this
> > will lead to a first class result, but I have some nervousness that
the
> > result might not be as effective as one might like.
>
> I have now made the three versions available:
>
>
http://www.whatwg.org/specs/web-apps/current-work/multipage/?style=complete
>
http://www.whatwg.org/specs/web-apps/current-work/multipage/?style=author
>    http://www.whatwg.org/specs/web-apps/current-work/multipage/?
> style=highlight

Ian:

I apologize for not having responded sooner. I was out on vacation for
several weeks when your note came in, and I just this evening noticed it
in my piles of unread email.  It will likely be awhile before I look at
the drafts you've prepared, but I do appreciate at very least the care
with which you've considered my comments.  I'm sorry for having let this
slip so long, and will let you know when I get to read the drafts.  Thank
you!

Noah

P.S. Notwithstanding the downsides of cross-posting, I'm cc:-ing www-tag,
as I know other TAG members will be interested in this work.

--------------------------------------
Noah Mendelsohn
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------








Ian Hickson <ian@...>
06/25/2009 09:04 PM
 
        To:     noah_mendelsohn@...
        cc:     public-html-comments@...
        Subject:        Re: Suggestions regarding creation of an
"Authoring Specification" for HTML 5


On Mon, 20 Oct 2008 noah_mendelsohn@... wrote:
>
> My overall comment is that I think the specification for the authoring
> of correct HTML 5 documents is of great importance.  I understand that
> you are hoping that the need can be met in part by, eventually, using
> scripts to produce a stripped down version of the existing draft,
> leaving out much of the parsing and error recovery detail.  Perhaps this

> will lead to a first class result, but I have some nervousness that the
> result might not be as effective as one might like.

I have now made the three versions available:

   
http://www.whatwg.org/specs/web-apps/current-work/multipage/?style=complete

   
http://www.whatwg.org/specs/web-apps/current-work/multipage/?style=author
   
http://www.whatwg.org/specs/web-apps/current-work/multipage/?style=highlight


They are also available on the W3C space as a single document that you can

dynamically change the view for using your browser's alternative style
sheet interface:

   http://dev.w3.org/html5/spec/


> * Simple success criteria should be explicitly set down for the
> authoring specification.  What information must it convey, to which
> audiences should it be comprehensible, etc.?  I'm not suggesting any
> big, elaborate, or time-consuming requirements effort, just a very brief

> set of criteria that could be agreed by the community as a yardstick for

> judging any particular draft.  Perhaps this already exists.

I've tried to clarify the expected audience here:

   
http://www.whatwg.org/specs/web-apps/current-work/multipage/introduction.html#audience


Is that what you had in mind?


> * I think it would be a good idea to generate representative drafts
> sooner rather than later.  If practical, this could be done by marking
> up the existing draft and running the full automated process.  If that's

> impractical soon, as I suspect may be the case, I would think that one
> or two members of the HTML working group could be tasked with manually
> producing a partial skeleton for evaluation, including at least some of
> the key sections such as 8.1, and representative slices of some of the
> others.  For example, if one or two microsyntaxes and the definitions of

> a few representative elements were converted, it would probably give a
> very good idea as to whether the presentation of all of them would
> eventually be effective.  I think the resulting draft should be
> circulated for comment, and should be used to inform planning for how
> the final HTML 5 authoring draft will eventually be prepared.

Doing the whole draft did not end up taking much work (just a couple of
weeks), so I just did the whole thing.


> * I think there are good reasons why most of the semantics of HTML 5 are

> explained in terms of the DOM, but it's worth keeping in mind that for
> authors (except when scripting), it's the serialized document that's of
> primary concern.  So, it's worth explaining clearly and early the key
> invariants of what a legal HTML 5 document looks like.  For example:
> "Start tags look like <this>, end tags look like </this>; elements are
> properly nested and thus encode a tree, which by the way is isomorphic
> to the corresponding DOM tree"; etc..
> Determining thinks like this from the existing specification is a bit of

> a theorem proving exercise:  you have to notice that the DOM is always a

> tree, even though browsers accept input that's poorly nested, you have
> to notice that there are serialization rules that invariably result in
> properly nested tags, and you have realize that those in turn define
> what is intented as legal HTML 5.  There's a risk that, if all one does
> is to strip the existing spec. to produce the authoring spec, these key
> aspects of correct HTML 5 will be unduly hard to discover.

I've tried to write a section that covers these basic points:

   
http://www.whatwg.org/specs/web-apps/current-work/multipage/introduction.html#a-quick-introduction-to-html



> * I think the authoring specification is important enough that attention

> should be given to introductory material, organization of the table of
> contents, etc.  Perhaps this comment is obvious, in which case I
> apologize for mentioning it.  Right now, I understand that the most
> critical section for authors is in section 8.1, so it's not immediately
> obvious that a simple stripping of the existing draft will result in a
> document that flows in sensible order, with key concepts suitably
> highlighted.

I don't think the syntax section is actually any more important for
authors than the semantics section, to be honest. There's not really much
point learning how to write until you have a vocabulary to write.

However, I've made the section mentioned above ("A quick introduction to
HTML") link to the syntax section, so for those who find this information
important there will now be a direct reference from the introduction
section to the syntax section.


> For example, I could imagine introductory material setting out some of
> the information mentioned in the bullet above.

I have attempted to do this.


> You could also any general syntactic rules, such as whether tags need to

> be explicitly closed or can be implicitly closed by the end tag for a
> parent, and if it's not obvious from the table of contents, provide
> simple guidance as to which sections are good starting points for
> learning key concepts.

I've tried to do this (in particular I've now included an explicit mention

of the rule that mis-nested tags aren't allowed).


> I hope these suggestions are helpful.

Very much so! Thank you very much. Please let me know if the changes I
have made are satisfactory, or if there is anything else I can do to
improve the specification.

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