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

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

>  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 11:15:09 UTC