- From: Murray Maloney <murray@muzmo.com>
- Date: Mon, 02 Feb 2009 15:53:20 -0500
- To: Lachlan Hunt <lachlan.hunt@lachy.id.au>
- Cc: public-html <public-html@w3.org>
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