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

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