- From: Murray Maloney <murray@muzmo.com>
- Date: Wed, 04 Feb 2009 08:27:14 -0500
- To: Lachlan Hunt <lachlan.hunt@lachy.id.au>
- Cc: public-html <public-html@w3.org>
At 12:14 PM 2/4/2009 +0100, Lachlan Hunt wrote: >Murray Maloney wrote: >>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. > >I've not heard of the dragon book before. Is this what you're referring to? > >http://en.wikipedia.org/wiki/Compilers:_Principles,_Techniques,_and_Tools Yep. >> Man pages are reference. > >Agreed. > >>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. > >Sitepoint's HTML Reference seems to be the closest example in terms of >content to the kind of document I'm producing. > >http://reference.sitepoint.com/html > >>>>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. > >I realised that after I sent, but where you referred to sections 3 and 4 >below, you didn't, which is why I added that. > >>>>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. > >Retaining and simplifying it is certainly one option I'm considering, >which is why it hasn't been dropped already. But I'd like to have more >content in the rest of the document before determining whether or not its >necessary. > >>>>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. > >I did mention that this was one of the sections that needed to be filled >in before going to FPWD. > >http://lists.w3.org/Archives/Public/public-html/2009Feb/0011.html > > >-- >Lachlan Hunt - Opera Software >http://lachy.id.au/ >http://www.opera.com/
Received on Wednesday, 4 February 2009 13:42:23 UTC