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.