Re: [html-author] Updates to the HTML Reference

Lachlan,

User's Guides and References are two distinctly different kinds of 
technical document.
References are typically normative documents intended to be authoritative.
Perhaps I missed something while I wasn't looking, but I didn't think that
was the document plan that the working group reviewed.

I propose that the title of the document should revert to "A Web 
Developers' Guide to HTML 5"
Please note that I have adjusted the position of the apostrophe because I 
believe that the
intent is that the document be 'a guide for web developers', rather than 'a 
guide by a web
developer'. Or am I mistaken?

I also observe that Section 5 "How to Read this Guide" indicates that "This 
section needs
major revision and may be dropped." Whereas I always need such a document, 
like a
Legend on a map. In particular, I would expect that Section 4's complex 
tabular layout
presupposes a reader's guide to its organization and meaning. I propose 
that Section 5
be shuffled forward in the document with an author's plan for a "Legend" or 
interpretation guide.

Finally, I observe that Section 3 lacks either content or a plan. I propose 
that it be removed
until such time as content or a plan emerges.


At 11:26 PM 2/1/2009 +0100, Lachlan Hunt wrote:

>Hi,
>   This is a summary of recent changes to the HTML 5 Reference [1].
>
>Formerly known as The Web Develoer's Guide to HTML 5, I renamed it to the 
>much shorter and more convenient title "HTML 5 Reference" with the 
>subtitle "A Web Developer’s Guide to HTML 5".
>
>The draft has now been divided into 3 major sections, each of which are 
>now clearly described in the introduction.  I'm hoping the intro will 
>clear up any misconceptions about how I intend to write the draft.
>
>I've begun writing the Getting Started with HTML 5 section, which is being 
>targetted at beginners who may have never written HTML before. Though it's 
>the content is very preliminary; expect it to be filled out a lot over the 
>coming weeks.
>
>I've also added element summaries for each element from the spec.  The 
>summaries themselves are currently generated entirely from the spec 
>itself, though I intend to add additional info to them later which isn't 
>as easy to scrape directly from the spec.
>
>The syntax section is currently missing.  I expect to significantly revise 
>what I had in previous drafts and incorporate it again later.
>
>[1] http://dev.w3.org/html5/html-author/
>
>--
>Lachlan Hunt - Opera Software
>http://lachy.id.au/
>http://www.opera.com/

Received on Monday, 2 February 2009 20:52:54 UTC