- From: Lachlan Hunt <lachlan.hunt@lachy.id.au>
- Date: Tue, 03 Feb 2009 02:52:06 +0100
- To: Murray Maloney <murray@muzmo.com>
- Cc: public-html <public-html@w3.org>
Murray Maloney wrote: > 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. Just to make sure we're understanding each other, please clearly describe your understanding of a reference and a guide, and how they differ. I have no intention of ever making it a normative document. I changed it to Reference to more accurately represent it's content. While there will be some tutorial-like introductory material, the bulk will serve as suitable reference material that explains each feature. > I propose that the title of the document should revert to "A Web > Developers' Guide to HTML 5" That title was too long, so I'd rather not. I may consider using HTML 5 Guide, though not until we are at least sure we have a common understanding of the two types of documents. > 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? Well, it works both ways, each with a slightly different meaning. When I initially came up with the title, I had in mind "The Hitchhiker's Guide to the Galaxy", which puts the apostrophe before the s. That's the singular possessive form that indicates the guide belongs to a hitchhiker, or, in this case, a web developer (that is, any web developer in possession of the guide, rather than one specific individual). What you propose is the plural possessive which indicates that it belongs collectively to all web developers. > I also observe that Section 5 "How to Read this Guide" ... Please note that it helps if you refer to section titles rather than section numbers, as it's possible that the section numbers may be altered later. > ... 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. It was moved the end to get it out of the way until I figure out what exactly to do with it. It was pointed out to me in IRC that making a beginner wade through that whole how to read section before even reaching the Getting Started section wasn't really the most effective approach for keeping the readers' attention. In general, I would prefer to make things relatively self explanatory, or only provide a brief explanation beforehand. But before making a file determination on this section, I'd like to wait and see how the rest of the content grows and changes first, and perhaps, if necessary, revisit that section and rewrite it later. > 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. I can assure you it has a plan. It's just not expressed within the document itself, beyond the short summary provided within the introduction. It even has some content that needs to be re-added to it. It was temporarily removed when the whole draft underwent a major restructuring recently and the content itself still needs to be restructured and revised accordingly. -- Lachlan Hunt - Opera Software http://lachy.id.au/ http://www.opera.com/
Received on Tuesday, 3 February 2009 01:52:47 UTC