W3C home > Mailing lists > Public > public-webplatform@w3.org > December 2013

Re: Proposed content design for HTML element pages

From: Max Polk <maxpolk@gmail.com>
Date: Fri, 06 Dec 2013 09:41:36 -0500
Message-ID: <52A1E220.7050200@gmail.com>
To: Jen Simmons <jen@jensimmons.com>, Alex Komoroske <komoroske@google.com>
CC: Eliot Graff <Eliot.Graff@microsoft.com>, Julee <julee@adobe.com>, WebPlatform Public List <public-webplatform@w3.org>, Eliezer Bernart <eliezerbernart@gmail.com>, David Singer <singer@apple.com>
On 12/6/2013 8:44 AM, Jen Simmons wrote:
> Hello all,
> I'm attaching two pdfs showing a proposed content design for the HTML 
> element pages. I've been designing using real content, so do read 
> what's there and think about whether/not this structure will work with 
> the range of content for HTML.
>
> I wanted to create enough structure to help enforce consistency, but 
> enough flexibility to support the diversity of elements. I also wrote 
> this content with newbies in mind  students, pro developers who still 
> haven't really learned the basics of HTML (sadly, that's a /huge/ 
> number of people), etc. Many of the other reference documents I looked 
> at expect a intermediate to advanced level of knowledge and mastery. 
> I'm hoping this group will agree that our documentation should work 
> for all levels of user  from total newbie to ultimate master. This 
> draft is my first attempt to find that balance.
>

I would call the "Needs name" section "Context" because it conveys the 
the category in the HTML5 schema, the positional context, tag omission 
(still slightly about context), DOM interface (how it lives in the DOM 
schema), and display properties (the display attribute contextually 
revelant information).

And instead of "Details" I would call it "Usage".  Except for the one 
history item at the top of the blockquote example (which is already in 
the history section by the way), everything there is about usage notes, 
usage tips, usage details.  The word "Usage" is stronger than the looser 
word "Details" and therefore perhaps more effective.

Lastly, do you believe it would be useful to have what you did on your 
Pro HTML5 demo with the "Open Editor" link so people can edit the 
example and see it change on the very page?  Basically it's a live 
editing concept where you see the results as you type.
Received on Friday, 6 December 2013 14:42:07 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:20:56 UTC