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

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.

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 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.

> 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.

> 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.

> ... 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.

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.

-- 
Lachlan Hunt - Opera Software
http://lachy.id.au/
http://www.opera.com/

Received on Tuesday, 3 February 2009 01:52:47 UTC