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