- From: Murray Maloney <murray@muzmo.com>
- Date: Tue, 03 Feb 2009 12:32:12 -0500
- To: Lachlan Hunt <lachlan.hunt@lachy.id.au>
- Cc: public-html <public-html@w3.org>
At 02:52 AM 2/3/2009 +0100, you wrote: >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. The Dragon book, for example, is a guide. Man pages are reference. I had understood that you intended to create a guide for web authors and developers. In that document, I expected to find out how to use, for example, forms and scripts. >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 can see the need for reference material, especially references that provide another view of the material in HTML 5 organized for ease of access - like man pages. But I didn't (and don't) think that a user guide and a technical reference should co-habit. >>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. Sure. >>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. Or, the guide used by developers -- not necessarily all, but certainly more than one. >>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. Ummm.... I mentioned section number and title here. >>... 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. That argues for keeping it concise and easy to follow. >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. I just thought that if you were publishing an WD, you would want to either include some content or remove it. Otherwise you will get lots of comments like this one. I thought that you could simply include a paragraph to explain roughly what is planned for the section, which might lead to comments that are more helpful. BTW, telling me that you can assure me of a plan does not assure me. Evidence of a plan does. This is me with my QA hat on.
Received on Tuesday, 3 February 2009 17:32:07 UTC