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

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