info
Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
"How to use HTML element" articles on MDN
3 views
Skip to first unread message
Jeremie Patonnier
Apr 8, 2015, 9:12:39 AM4/8/15
to dev-mdc, Mozilla Webmaker list
Hi!
Among the various plan we have to improve HTML for beginners on MDN, we
need to create a series of articles on how to use each HTML element.
The plan is to write one article per element but with a few notable
exception: <input> should be split into one article per input type; and
some HTML element cannot be used without other element such as <figure> and
<figcaption>, <legend> and <fieldset>, or <detail> and <summary>.
There is also some known complexe structure in HTML such as form and tables
but it's out of scope to write a full fledge tutorial about those specific
structure (we actually already have one for forms). In such cases, the
articles should focus on a given element and open up to the other one that
could be necessary to provide a full overview of the structure.
So the question is what should we put in those articles?
In my opinion, we should provide concrete example of common use case (with
code) and provide an example of each attribute usage support by a given
element. Each example should explain the why and the how. Providing a focus
on semantic and accessibility would be a huge plus.
In term of structure, we should start with a quick summary of the use case
we will cover then provide a section per example (which will allow to use
the MDN LiveSample system to turn all our examples into actual working
code). At the end we should open up with link (a see also section) that
will link to the reference documentation as well as to other more complexe
tutorial.
Those are just my first random though about that, I would love to hear your
opinion about that.
Best,
--
Jeremie
.............................
Web : http://jeremie.patonnier.net
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
Among the various plan we have to improve HTML for beginners on MDN, we
need to create a series of articles on how to use each HTML element.
The plan is to write one article per element but with a few notable
exception: <input> should be split into one article per input type; and
some HTML element cannot be used without other element such as <figure> and
<figcaption>, <legend> and <fieldset>, or <detail> and <summary>.
There is also some known complexe structure in HTML such as form and tables
but it's out of scope to write a full fledge tutorial about those specific
structure (we actually already have one for forms). In such cases, the
articles should focus on a given element and open up to the other one that
could be necessary to provide a full overview of the structure.
So the question is what should we put in those articles?
In my opinion, we should provide concrete example of common use case (with
code) and provide an example of each attribute usage support by a given
element. Each example should explain the why and the how. Providing a focus
on semantic and accessibility would be a huge plus.
In term of structure, we should start with a quick summary of the use case
we will cover then provide a section per example (which will allow to use
the MDN LiveSample system to turn all our examples into actual working
code). At the end we should open up with link (a see also section) that
will link to the reference documentation as well as to other more complexe
tutorial.
Those are just my first random though about that, I would love to hear your
opinion about that.
Best,
--
Jeremie
.............................
Web : http://jeremie.patonnier.net
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
Chris Mills
Apr 8, 2015, 9:51:48 AM4/8/15
to Jeremie Patonnier, dev-mdc, Mozilla Webmaker list
* Introduction - give high level usage of element(s)
* Hello world, basic example
* Advanced usage #1
* Advanced usage #2
* Advanced Usage #n (include as many of these sections as is necessary to show all of the major use cases for the element(s) in question. As said above, include one example per section to take advantage of LiveSamples. Note that I think these should be per task, not per element or attribute, as the landing page already lists the elements/attributes, and you could always link those to specific sections of the “Using…” article for more information and examples. Doing it this way allows you to have a dual searching purpose - people can search for “<img> alt attribute” or “adding alternative text to images” and still find useful information.)
* Tips/Best practices section. Optional section to include any best practices/gotchas that aren’t already covered in the advanced usage sections. E.g. accessibility gotchas
* Browser support
* Backwards compatibility (include fallback info, polyfills, feature detection, etc.)
* See also (include link to reference landing page, spec, etc.)
Jeremie Patonnier
Apr 8, 2015, 10:27:34 AM4/8/15
to Chris Mills, dev-mdc, Mozilla Webmaker list
Hi!
2015-04-08 11:52 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
>
> What you say here pretty much makes sense. I’d have a typical structure
> something like this:
>
> * Introduction - give high level usage of element(s)
> * Hello world, basic example
>
Just a note but I know we all agree on that: examples must be clean enough
to be copy/past-able.
> * Advanced usage #1
> * Advanced usage #2
> * Advanced Usage #n (include as many of these sections as is necessary to
> show all of the major use cases for the element(s) in question. As said
> above, include one example per section to take advantage of LiveSamples.
> Note that I think these should be per task, not per element or attribute,
> as the landing page already lists the elements/attributes, and you could
> always link those to specific sections of the “Using…” article for more
> information and examples. Doing it this way allows you to have a dual
> searching purpose - people can search for “<img> alt attribute” or “adding
> alternative text to images” and still find useful information.)
>
I agree the task oriented wording is better, but I stress the fact that,
whatever happen all attributes should get one example demonstrating how to
use them one way or another. We also have plan to work on specifics
articles dedicated on how to solve problems with HTML (more about this by
the end of the month). Those "Using the # element" articles remain quite
technical and are targeting beginners or average developers that want to
dig into some technical edge cases on a specific element.
> * Tips/Best practices section. Optional section to include any best
> practices/gotchas that aren’t already covered in the advanced usage
> sections. E.g. accessibility gotchas
>
+1
> * Browser support
> * Backwards compatibility (include fallback info, polyfills, feature
> detection, etc.)
>
+1
> * See also (include link to reference landing page, spec, etc.)
Not sure the specs are relevant in such articles (they are more useful in
the associated reference article)
2015-04-08 11:52 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
>
> What you say here pretty much makes sense. I’d have a typical structure
> something like this:
>
> * Introduction - give high level usage of element(s)
> * Hello world, basic example
>
to be copy/past-able.
> * Advanced usage #1
> * Advanced usage #2
> * Advanced Usage #n (include as many of these sections as is necessary to
> show all of the major use cases for the element(s) in question. As said
> above, include one example per section to take advantage of LiveSamples.
> Note that I think these should be per task, not per element or attribute,
> as the landing page already lists the elements/attributes, and you could
> always link those to specific sections of the “Using…” article for more
> information and examples. Doing it this way allows you to have a dual
> searching purpose - people can search for “<img> alt attribute” or “adding
> alternative text to images” and still find useful information.)
>
whatever happen all attributes should get one example demonstrating how to
use them one way or another. We also have plan to work on specifics
articles dedicated on how to solve problems with HTML (more about this by
the end of the month). Those "Using the # element" articles remain quite
technical and are targeting beginners or average developers that want to
dig into some technical edge cases on a specific element.
> * Tips/Best practices section. Optional section to include any best
> practices/gotchas that aren’t already covered in the advanced usage
> sections. E.g. accessibility gotchas
>
> * Browser support
> * Backwards compatibility (include fallback info, polyfills, feature
> detection, etc.)
>
> * See also (include link to reference landing page, spec, etc.)
the associated reference article)
Chris Mills
Apr 8, 2015, 12:12:03 PM4/8/15
to Jeremie Patonnier, dev-mdc, Mozilla Webmaker list
> On 8 Apr 2015, at 15:26, Jeremie Patonnier <jeremie....@gmail.com> wrote:
>
> Hi!
>
> 2015-04-08 11:52 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
> What you say here pretty much makes sense. I’d have a typical structure something like this:
>
> * Introduction - give high level usage of element(s)
> * Hello world, basic example
>
> Just a note but I know we all agree on that: examples must be clean enough to be copy/past-able.
>
> * Advanced usage #1
> * Advanced usage #2
> * Advanced Usage #n (include as many of these sections as is necessary to show all of the major use cases for the element(s) in question. As said above, include one example per section to take advantage of LiveSamples. Note that I think these should be per task, not per element or attribute, as the landing page already lists the elements/attributes, and you could always link those to specific sections of the “Using…” article for more information and examples. Doing it this way allows you to have a dual searching purpose - people can search for “<img> alt attribute” or “adding alternative text to images” and still find useful information.)
>
> I agree the task oriented wording is better, but I stress the fact that, whatever happen all attributes should get one example demonstrating how to use them one way or another.
> We also have plan to work on specifics articles dedicated on how to solve problems with HTML (more about this by the end of the month). Those "Using the # element" articles remain quite technical and are targeting beginners or average developers that want to dig into some technical edge cases on a specific element.
>
> * Tips/Best practices section. Optional section to include any best practices/gotchas that aren’t already covered in the advanced usage sections. E.g. accessibility gotchas
>
> +1
>
> * Browser support
> * Backwards compatibility (include fallback info, polyfills, feature detection, etc.)
>
> +1
>
> * See also (include link to reference landing page, spec, etc.)
>
> Not sure the specs are relevant in such articles (they are more useful in the associated reference article)
Jeremie Patonnier
Apr 8, 2015, 2:08:53 PM4/8/15
to Chris Mills, dev-mdc, Mozilla Webmaker list
Hi!
I went through all the HTML Elements documented on MDN to see how that
"Using the # element" can fit and I came with the following various cases:
1. *Elements that we shouldn't bother about (Obsolete, Deprecated,
non-standard or web component):* acronym, applet, basefont, bgsound,
big, blink, center, command, dir, font, frame, frameset, image, isindex,
listing, marquee, multicol, nobr, noembed, noframes, plaintext, spacer,
strike, tt, xmp, content, element, shadow, template.
2. *Elements that are quite straight forward to write about (as they are
solving problems on their own or are complexe enough to deserve a dedicated
article):* a, abbr, audio, base, data, datalist, dfn, dialog, embed,
iframe, img, keygen, link, meta, meter, option (*as it is usable with
select (and optgroup) and datalist it deserves its own article*),
output, picture, progress, script, source (*as it is usable with audio,
video and picture it deserves its own article*), style, time, track,
video
3. *Elements from complexe structures but complexe enough to deserve
their own article (basically it's form and table related elements):*
1. Forms (all those element's articles should provide follow up links
to the Form tutorial
<https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Forms> to
see how they interact): button, form, input (*actually one article
per input type*), label, textarea
2. Table (We are missing a dedicated tutorial about HTML tables to
provide follow up to those articles): caption, table, td, th, tr
4. *Elements that are part of a structure that cannot be break and
should be the object of a single article:* map & area, col & colgroup,
dl & dt & dd, details & summary, fieldset & legend, figure & figcaption,
h1...h6 & hgroup, ol & ul & li, menu & menuitem, select & optgroup, object
& param, ruby & rp & rt & rtc
5. *Elements that are technically so simple that a dedicated article is
meaningless but can be group under the umbrella of a single article as they
are relatives to a single semantic problem:*
- Internationalizing HTML documents: bdi, bdo
- Handling citation in HTML: blockquote, cite, q
- Handling text insertion and deletion in HTML: del, ins
- Sectioning html document: article, aside, div, footer, header,
main, nav, section
- Using HTML text level semantic: b, em, i, mark, s, small, span,
strong, sub, sup, u
- Handling HTML basic structure: body, head, html, title
- Dealing with line breaking: br, hr, wbr
- Managing table structure: tbody, tfoot, thead
6. *A few element I really don't know what to do with :-/ They are to
simple to use with a very simple semantic to deserve a dedicated article
and I cannot figure how to group them under a logical umbrella:* canvas,
code, kbd, noscript, p, pre, samp, var.
So my suggestion is that we should first prioritize 2 and 4 (very
straightforward writing to handle) then handle 3 (also straightforward but
some care has to be taken to handle the relation between those articles)
and finish with 5. If you have any suggestion/idea about 6 please share :)
Does that sounds like a reasonable plan? Any idea, suggestion, opinions
about the classification above ?
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
I went through all the HTML Elements documented on MDN to see how that
"Using the # element" can fit and I came with the following various cases:
1. *Elements that we shouldn't bother about (Obsolete, Deprecated,
non-standard or web component):* acronym, applet, basefont, bgsound,
big, blink, center, command, dir, font, frame, frameset, image, isindex,
listing, marquee, multicol, nobr, noembed, noframes, plaintext, spacer,
strike, tt, xmp, content, element, shadow, template.
2. *Elements that are quite straight forward to write about (as they are
solving problems on their own or are complexe enough to deserve a dedicated
article):* a, abbr, audio, base, data, datalist, dfn, dialog, embed,
iframe, img, keygen, link, meta, meter, option (*as it is usable with
select (and optgroup) and datalist it deserves its own article*),
output, picture, progress, script, source (*as it is usable with audio,
video and picture it deserves its own article*), style, time, track,
video
3. *Elements from complexe structures but complexe enough to deserve
their own article (basically it's form and table related elements):*
1. Forms (all those element's articles should provide follow up links
to the Form tutorial
<https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Forms> to
see how they interact): button, form, input (*actually one article
per input type*), label, textarea
2. Table (We are missing a dedicated tutorial about HTML tables to
provide follow up to those articles): caption, table, td, th, tr
4. *Elements that are part of a structure that cannot be break and
should be the object of a single article:* map & area, col & colgroup,
dl & dt & dd, details & summary, fieldset & legend, figure & figcaption,
h1...h6 & hgroup, ol & ul & li, menu & menuitem, select & optgroup, object
& param, ruby & rp & rt & rtc
5. *Elements that are technically so simple that a dedicated article is
meaningless but can be group under the umbrella of a single article as they
are relatives to a single semantic problem:*
- Internationalizing HTML documents: bdi, bdo
- Handling citation in HTML: blockquote, cite, q
- Handling text insertion and deletion in HTML: del, ins
- Sectioning html document: article, aside, div, footer, header,
main, nav, section
- Using HTML text level semantic: b, em, i, mark, s, small, span,
strong, sub, sup, u
- Handling HTML basic structure: body, head, html, title
- Dealing with line breaking: br, hr, wbr
- Managing table structure: tbody, tfoot, thead
6. *A few element I really don't know what to do with :-/ They are to
simple to use with a very simple semantic to deserve a dedicated article
and I cannot figure how to group them under a logical umbrella:* canvas,
code, kbd, noscript, p, pre, samp, var.
So my suggestion is that we should first prioritize 2 and 4 (very
straightforward writing to handle) then handle 3 (also straightforward but
some care has to be taken to handle the relation between those articles)
and finish with 5. If you have any suggestion/idea about 6 please share :)
Does that sounds like a reasonable plan? Any idea, suggestion, opinions
about the classification above ?
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
Chris Mills
Apr 8, 2015, 4:14:19 PM4/8/15
to Jeremie Patonnier, dev-mdc, Mozilla Webmaker list
I basically agree with all of this, and think it sounds super…a few comments below...
Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills
> On 8 Apr 2015, at 19:08, Jeremie Patonnier <jeremie....@gmail.com> wrote:
>
> Hi!
>
> I went through all the HTML Elements documented on MDN to see how that "Using the # element" can fit and I came with the following various cases:
>
> • Elements that we shouldn't bother about (Obsolete, Deprecated, non-standard or web component): acronym, applet, basefont, bgsound, big, blink, center, command, dir, font, frame, frameset, image, isindex, listing, marquee, multicol, nobr, noembed, noframes, plaintext, spacer, strike, tt, xmp, content, element, shadow, template.
>
> • Elements that are quite straight forward to write about (as they are solving problems on their own or are complexe enough to deserve a dedicated article): a, abbr, audio, base, data, datalist, dfn, dialog, embed, iframe, img, keygen, link, meta, meter, option (as it is usable with select (and optgroup) and datalist it deserves its own article), output, picture, progress, script, source (as it is usable with audio, video and picture it deserves its own article), style, time, track, video
>
> • Elements from complexe structures but complexe enough to deserve their own article (basically it's form and table related elements):
> • Forms (all those element's articles should provide follow up links to the Form tutorial to see how they interact): button, form, input (actually one article per input type), label, textarea
> • Table (We are missing a dedicated tutorial about HTML tables to provide follow up to those articles): caption, table, td, th, tr
>
> • Elements that are part of a structure that cannot be break and should be the object of a single article: map & area, col & colgroup, dl & dt & dd, details & summary, fieldset & legend, figure & figcaption, h1...h6 & hgroup, ol & ul & li, menu & menuitem, select & optgroup, object & param, ruby & rp & rt & rtc
option/optgroup/select should probably fit into this group?
should we also group together audio/video/source, since source is used the same in both, and audio/video share many of the same attributes/API features? picture is also similar, but should be given special treatment because it is more recent and has some notable differences.
>
> • Elements that are technically so simple that a dedicated article is meaningless but can be group under the umbrella of a single article as they are relatives to a single semantic problem:
> • Internationalizing HTML documents: bdi, bdo
> • Handling citation in HTML: blockquote, cite, q
> • Handling text insertion and deletion in HTML: del, ins
> • Sectioning html document: article, aside, div, footer, header, main, nav, section
> • Using HTML text level semantic: b, em, i, mark, s, small, span, strong, sub, sup, u
> • Handling HTML basic structure: body, head, html, title
> • Dealing with line breaking: br, hr, wbr
> • Managing table structure: tbody, tfoot, thead
>
> • A few element I really don't know what to do with :-/ They are to simple to use with a very simple semantic to deserve a dedicated article and I cannot figure how to group them under a logical umbrella: canvas
canvas deserves a special article, imo - it is simple on its own, but does have a number of best practices worthy of mention, plus we could perhaps mention polyfills, number of gaming libraries, etc. that generate canvas, other stuff beyond the pure element semantics?
> code, kbd, noscript, p, pre, samp, var.
code, kbd, pre, samp and var can arguably go in HTML text level semantics.
noscript is a tricky one. It probably warrants its own article, to provide a fairly detailed use case as so few people really know how to use it properly (although this is because it is so rarely used these days.)
p is a funny one on its own. You could either just lump it into HTML text level semantics, or you could put it in an article abut h1-h6, talking about correct document hierarchies and the a11y advantages thereof.
> So my suggestion is that we should first prioritize 2 and 4 (very straightforward writing to handle) then handle 3 (also straightforward but some care has to be taken to handle the relation between those articles) and finish with 5. If you have any suggestion/idea about 6 please share :)
Sounds like a good order to put them in.
Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills
> On 8 Apr 2015, at 19:08, Jeremie Patonnier <jeremie....@gmail.com> wrote:
>
> Hi!
>
> I went through all the HTML Elements documented on MDN to see how that "Using the # element" can fit and I came with the following various cases:
>
>
> • Elements that are quite straight forward to write about (as they are solving problems on their own or are complexe enough to deserve a dedicated article): a, abbr, audio, base, data, datalist, dfn, dialog, embed, iframe, img, keygen, link, meta, meter, option (as it is usable with select (and optgroup) and datalist it deserves its own article), output, picture, progress, script, source (as it is usable with audio, video and picture it deserves its own article), style, time, track, video
>
> • Elements from complexe structures but complexe enough to deserve their own article (basically it's form and table related elements):
> • Forms (all those element's articles should provide follow up links to the Form tutorial to see how they interact): button, form, input (actually one article per input type), label, textarea
> • Table (We are missing a dedicated tutorial about HTML tables to provide follow up to those articles): caption, table, td, th, tr
>
> • Elements that are part of a structure that cannot be break and should be the object of a single article: map & area, col & colgroup, dl & dt & dd, details & summary, fieldset & legend, figure & figcaption, h1...h6 & hgroup, ol & ul & li, menu & menuitem, select & optgroup, object & param, ruby & rp & rt & rtc
option/optgroup/select should probably fit into this group?
should we also group together audio/video/source, since source is used the same in both, and audio/video share many of the same attributes/API features? picture is also similar, but should be given special treatment because it is more recent and has some notable differences.
>
> • Elements that are technically so simple that a dedicated article is meaningless but can be group under the umbrella of a single article as they are relatives to a single semantic problem:
> • Internationalizing HTML documents: bdi, bdo
> • Handling citation in HTML: blockquote, cite, q
> • Handling text insertion and deletion in HTML: del, ins
> • Sectioning html document: article, aside, div, footer, header, main, nav, section
> • Using HTML text level semantic: b, em, i, mark, s, small, span, strong, sub, sup, u
> • Handling HTML basic structure: body, head, html, title
> • Dealing with line breaking: br, hr, wbr
> • Managing table structure: tbody, tfoot, thead
>
> • A few element I really don't know what to do with :-/ They are to simple to use with a very simple semantic to deserve a dedicated article and I cannot figure how to group them under a logical umbrella: canvas
canvas deserves a special article, imo - it is simple on its own, but does have a number of best practices worthy of mention, plus we could perhaps mention polyfills, number of gaming libraries, etc. that generate canvas, other stuff beyond the pure element semantics?
> code, kbd, noscript, p, pre, samp, var.
noscript is a tricky one. It probably warrants its own article, to provide a fairly detailed use case as so few people really know how to use it properly (although this is because it is so rarely used these days.)
p is a funny one on its own. You could either just lump it into HTML text level semantics, or you could put it in an article abut h1-h6, talking about correct document hierarchies and the a11y advantages thereof.
> So my suggestion is that we should first prioritize 2 and 4 (very straightforward writing to handle) then handle 3 (also straightforward but some care has to be taken to handle the relation between those articles) and finish with 5. If you have any suggestion/idea about 6 please share :)
Jeremie Patonnier
Apr 9, 2015, 5:26:42 AM4/9/15
to Chris Mills, dev-mdc, Mozilla Webmaker list
Hi :)
2015-04-08 22:14 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
>
> > On 8 Apr 2015, at 19:08, Jeremie Patonnier <jeremie....@gmail.com>
> wrote:
> > • Elements that are part of a structure that cannot be break and
> should be the object of a single article: map & area, col & colgroup, dl &
> dt & dd, details & summary, fieldset & legend, figure & figcaption, h1...h6
> & hgroup, ol & ul & li, menu & menuitem, select & optgroup, object & param,
> ruby & rp & rt & rtc
>
> option/optgroup/select should probably fit into this group?
>
Yes probably, I originally set option out of optgroup/select because it is
also used within datalist. But as the main usage for option is within
select, it make more sens to put it into the same bucket and just focus on
datalist alone with some follow up to the select/optgroup/option article
(as one of the known fallback for datalist is using select, it makes total
sens)
> should we also group together audio/video/source, since source is used the
> same in both, and audio/video share many of the same attributes/API
> features? picture is also similar, but should be given special treatment
> because it is more recent and has some notable differences.
>
I that case I tend to disagree.
First, even if audio and video share many attributes they have their own
specificities and use cases that are quite different. Regarding the API, I
don't want to cover any DOM stuff in those articles (it carry unnecessary
complexity at that point). It's really all about HTML (but it's possible to
open up to other articles and I think we already have something about the
audio/video API). So I prefer 2 shorter articles that overlap a bit rather
than a long clumsy article.
Second, I really don't know what to do with source as its usage is somewhat
different within picture and audio/video (but not that different). If we
have to put source in a bucket with one of those I would rather do it with
picture as it handles way more advance stuff in here and picture is totally
useless without source (where audio and video can be used without source).
> • A few element I really don't know what to do with :-/ They are to
> simple to use with a very simple semantic to deserve a dedicated article
> and I cannot figure how to group them under a logical umbrella: canvas
>
> canvas deserves a special article, imo - it is simple on its own, but does
> have a number of best practices worthy of mention, plus we could perhaps
> mention polyfills, number of gaming libraries, etc. that generate canvas,
> other stuff beyond the pure element semantics?
>
Mmmh... possibly yes, I tend to think that we already have the Canvas 2D
tutorial to cover many of this. But yes, using such an article to show off
what canvas can be used for is a good idea (even if I'm always a bit
reluctant to name specific libraries on MDN... which is to prescriptive
IMO. But in that case it could be okay as the canvas element is totally
useless without JavaScript)
> code, kbd, noscript, p, pre, samp, var.
>
> code, kbd, pre, samp and var can arguably go in HTML text level semantics.
>
Technically speaking yes... I'm just wondering how large that article could
be and if there isn't a way to split it up. But if there is no other idea;
let's do that.
> noscript is a tricky one. It probably warrants its own article, to provide
> a fairly detailed use case as so few people really know how to use it
> properly (although this is because it is so rarely used these days.)
>
Yes, you're right. Let's do that.
> p is a funny one on its own. You could either just lump it into HTML text
> level semantics, or you could put it in an article abut h1-h6, talking
> about correct document hierarchies and the a11y advantages thereof.
>
Both sounds okay to me, let's postpone any decision about it utils we have
some concrete content. It will help us decide.
I will draft a few more stuff by next week and I think we will be good to
go: an article that could be used as example; a landing page for that set
of articles in the Learning Area); and a few meta entry point (trello
board, URL schema and hierarchy for those articles, and so on)
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
2015-04-08 22:14 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
>
> > On 8 Apr 2015, at 19:08, Jeremie Patonnier <jeremie....@gmail.com>
> wrote:
> > • Elements that are part of a structure that cannot be break and
> should be the object of a single article: map & area, col & colgroup, dl &
> dt & dd, details & summary, fieldset & legend, figure & figcaption, h1...h6
> & hgroup, ol & ul & li, menu & menuitem, select & optgroup, object & param,
> ruby & rp & rt & rtc
>
> option/optgroup/select should probably fit into this group?
>
also used within datalist. But as the main usage for option is within
select, it make more sens to put it into the same bucket and just focus on
datalist alone with some follow up to the select/optgroup/option article
(as one of the known fallback for datalist is using select, it makes total
sens)
> should we also group together audio/video/source, since source is used the
> same in both, and audio/video share many of the same attributes/API
> features? picture is also similar, but should be given special treatment
> because it is more recent and has some notable differences.
>
First, even if audio and video share many attributes they have their own
specificities and use cases that are quite different. Regarding the API, I
don't want to cover any DOM stuff in those articles (it carry unnecessary
complexity at that point). It's really all about HTML (but it's possible to
open up to other articles and I think we already have something about the
audio/video API). So I prefer 2 shorter articles that overlap a bit rather
than a long clumsy article.
Second, I really don't know what to do with source as its usage is somewhat
different within picture and audio/video (but not that different). If we
have to put source in a bucket with one of those I would rather do it with
picture as it handles way more advance stuff in here and picture is totally
useless without source (where audio and video can be used without source).
> • A few element I really don't know what to do with :-/ They are to
> simple to use with a very simple semantic to deserve a dedicated article
> and I cannot figure how to group them under a logical umbrella: canvas
>
> canvas deserves a special article, imo - it is simple on its own, but does
> have a number of best practices worthy of mention, plus we could perhaps
> mention polyfills, number of gaming libraries, etc. that generate canvas,
> other stuff beyond the pure element semantics?
>
tutorial to cover many of this. But yes, using such an article to show off
what canvas can be used for is a good idea (even if I'm always a bit
reluctant to name specific libraries on MDN... which is to prescriptive
IMO. But in that case it could be okay as the canvas element is totally
useless without JavaScript)
> code, kbd, noscript, p, pre, samp, var.
>
> code, kbd, pre, samp and var can arguably go in HTML text level semantics.
>
be and if there isn't a way to split it up. But if there is no other idea;
let's do that.
> noscript is a tricky one. It probably warrants its own article, to provide
> a fairly detailed use case as so few people really know how to use it
> properly (although this is because it is so rarely used these days.)
>
> p is a funny one on its own. You could either just lump it into HTML text
> level semantics, or you could put it in an article abut h1-h6, talking
> about correct document hierarchies and the a11y advantages thereof.
>
some concrete content. It will help us decide.
I will draft a few more stuff by next week and I think we will be good to
go: an article that could be used as example; a landing page for that set
of articles in the Learning Area); and a few meta entry point (trello
board, URL schema and hierarchy for those articles, and so on)
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
Chris Mills
Apr 9, 2015, 6:32:23 AM4/9/15
to Jeremie Patonnier, dev-mdc, Mozilla Webmaker list
> On 9 Apr 2015, at 10:25, Jeremie Patonnier <jeremie....@gmail.com> wrote:
>
> Hi :)
>
> 2015-04-08 22:14 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
> > On 8 Apr 2015, at 19:08, Jeremie Patonnier <jeremie....@gmail.com> wrote:
> > • Elements that are part of a structure that cannot be break and should be the object of a single article: map & area, col & colgroup, dl & dt & dd, details & summary, fieldset & legend, figure & figcaption, h1...h6 & hgroup, ol & ul & li, menu & menuitem, select & optgroup, object & param, ruby & rp & rt & rtc
>
> option/optgroup/select should probably fit into this group?
>
> Yes probably, I originally set option out of optgroup/select because it is also used within datalist. But as the main usage for option is within select, it make more sens to put it into the same bucket and just focus on datalist alone with some follow up to the select/optgroup/option article (as one of the known fallback for datalist is using select, it makes total sens)
>
> should we also group together audio/video/source, since source is used the same in both, and audio/video share many of the same attributes/API features? picture is also similar, but should be given special treatment because it is more recent and has some notable differences.
>
> I that case I tend to disagree.
>
> First, even if audio and video share many attributes they have their own specificities and use cases that are quite different. Regarding the API, I don't want to cover any DOM stuff in those articles (it carry unnecessary complexity at that point). It's really all about HTML (but it's possible to open up to other articles and I think we already have something about the audio/video API). So I prefer 2 shorter articles that overlap a bit rather than a long clumsy article.
>
> Second, I really don't know what to do with source as its usage is somewhat different within picture and audio/video (but not that different). If we have to put source in a bucket with one of those I would rather do it with picture as it handles way more advance stuff in here and picture is totally useless without source (where audio and video can be used without source).
>
> > • A few element I really don't know what to do with :-/ They are to simple to use with a very simple semantic to deserve a dedicated article and I cannot figure how to group them under a logical umbrella: canvas
>
> canvas deserves a special article, imo - it is simple on its own, but does have a number of best practices worthy of mention, plus we could perhaps mention polyfills, number of gaming libraries, etc. that generate canvas, other stuff beyond the pure element semantics?
>
> Mmmh... possibly yes, I tend to think that we already have the Canvas 2D tutorial to cover many of this. But yes, using such an article to show off what canvas can be used for is a good idea (even if I'm always a bit reluctant to name specific libraries on MDN... which is to prescriptive IMO. But in that case it could be okay as the canvas element is totally useless without JavaScript)
>
> > code, kbd, noscript, p, pre, samp, var.
>
> code, kbd, pre, samp and var can arguably go in HTML text level semantics.
>
> Technically speaking yes... I'm just wondering how large that article could be and if there isn't a way to split it up. But if there is no other idea; let's do that.
>
> noscript is a tricky one. It probably warrants its own article, to provide a fairly detailed use case as so few people really know how to use it properly (although this is because it is so rarely used these days.)
>
> Yes, you're right. Let's do that.
>
> p is a funny one on its own. You could either just lump it into HTML text level semantics, or you could put it in an article abut h1-h6, talking about correct document hierarchies and the a11y advantages thereof.
>
> Both sounds okay to me, let's postpone any decision about it utils we have some concrete content. It will help us decide.
>
> I will draft a few more stuff by next week and I think we will be good to go: an article that could be used as example; a landing page for that set of articles in the Learning Area); and a few meta entry point (trello board, URL schema and hierarchy for those articles, and so on)
>
Jeremie Patonnier
Apr 14, 2015, 8:26:04 AM4/14/15
to Chris Mills, dev-mdc, Mozilla Webmaker list
Hi :)
So I start shaping things up to start the writing work:
- HTML Elements guide:
https://developer.mozilla.org/en-US/Learn/HTML/Element
This is the landing page for people who want to learn HTML tags. It is
divided in two: First is the list of all HTML tags put into bucket
categories. Nice for people who have a generic issue or want to know
straighforward how to use element X. Second an embryo of common use cases
that HTML is made to solve. Ideal for people who want to know how to do X
with HTML This is just a first intentent, suggestion of improvement welcome.
- Using the <abbr> element:
https://developer.mozilla.org/en-US/Learn/HTML/Element/abbr
This an example of how a simple Using the X element articles could looks
like. It is a very simple one and some other could be way more complicated.
As stated in that discussion thread, not all HTML element deserve such a
dedicated article. But even if some articles cover many elements at once, I
think it's important to have a straightforward URL schema
(/en-US/Learn/HTML/Element/XXX) to have a consistent access to each element
article (even if they redirect to another article)
- The <abbr> refrence page:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr
I reshape the reference page to better fit with the Using the <abbr>
article. It is way more easier and up to date.
If you're okay with that, I'll set up some meta documentation on MDN and
Trello to actively start writing :)
Best,
Jeremie
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
So I start shaping things up to start the writing work:
- HTML Elements guide:
https://developer.mozilla.org/en-US/Learn/HTML/Element
This is the landing page for people who want to learn HTML tags. It is
divided in two: First is the list of all HTML tags put into bucket
categories. Nice for people who have a generic issue or want to know
straighforward how to use element X. Second an embryo of common use cases
that HTML is made to solve. Ideal for people who want to know how to do X
with HTML This is just a first intentent, suggestion of improvement welcome.
- Using the <abbr> element:
https://developer.mozilla.org/en-US/Learn/HTML/Element/abbr
This an example of how a simple Using the X element articles could looks
like. It is a very simple one and some other could be way more complicated.
As stated in that discussion thread, not all HTML element deserve such a
dedicated article. But even if some articles cover many elements at once, I
think it's important to have a straightforward URL schema
(/en-US/Learn/HTML/Element/XXX) to have a consistent access to each element
article (even if they redirect to another article)
- The <abbr> refrence page:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr
I reshape the reference page to better fit with the Using the <abbr>
article. It is way more easier and up to date.
If you're okay with that, I'll set up some meta documentation on MDN and
Trello to actively start writing :)
Best,
Jeremie
Janet Swisher
Apr 14, 2015, 12:50:52 PM4/14/15
to Jeremie Patonnier, Chris Mills, dev-mdc, Mozilla Webmaker list
In general, I like the direction of this, but I want to strongly
discourage article titles like "How to use the <abbr> element". This is
NOT a task-oriented title. A task-oriented title would be "How to
indicate abbreviations".
If you were documenting an application user interface, you would
describe "How to print a document", not "How to use the print dialog
box". One describes the user's goal; the other describes the program
structure. Start from user's goal, and use it to teach the
program/language structure.
This may seem obvious, as we have discussed the different categories of
elements that need to be documented, etc. But early examples like this
tend to get copied more literally than you would expect. Not everybody
writing articles will have the context of these discussions.
Janet Swisher <mailto:jREMOVE...@mozilla.com>
Mozilla Developer Network <https://developer.mozilla.org>
MDN Community Manager
discourage article titles like "How to use the <abbr> element". This is
NOT a task-oriented title. A task-oriented title would be "How to
indicate abbreviations".
If you were documenting an application user interface, you would
describe "How to print a document", not "How to use the print dialog
box". One describes the user's goal; the other describes the program
structure. Start from user's goal, and use it to teach the
program/language structure.
This may seem obvious, as we have discussed the different categories of
elements that need to be documented, etc. But early examples like this
tend to get copied more literally than you would expect. Not everybody
writing articles will have the context of these discussions.
Mozilla Developer Network <https://developer.mozilla.org>
MDN Community Manager
Jeremie Patonnier
Apr 14, 2015, 12:57:54 PM4/14/15
to Janet Swisher, dev-mdc, Chris Mills, Mozilla Webmaker list
100% Agreed with you.
Making such a test run make it easier to spot all of this. I gonna make
some change on those test articles to fixe that by tomorrow :)
> 2015-04-09 12:32 GMT+02:00 Chris Mills <cmi...@mozilla.com> <cmi...@mozilla.com>:
>
>
> On 9 Apr 2015, at 10:25, Jeremie Patonnier <jeremie....@gmail.com> <jeremie....@gmail.com>
>
> wrote:
>
> Hi :)
>
> 2015-04-08 22:14 GMT+02:00 Chris Mills <cmi...@mozilla.com> <cmi...@mozilla.com>:
> Janet Swisher <jREMOVE...@mozilla.com>
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
Making such a test run make it easier to spot all of this. I gonna make
some change on those test articles to fixe that by tomorrow :)
>
>
> On 9 Apr 2015, at 10:25, Jeremie Patonnier <jeremie....@gmail.com> <jeremie....@gmail.com>
>
> wrote:
>
> Hi :)
>
> 2015-04-08 22:14 GMT+02:00 Chris Mills <cmi...@mozilla.com> <cmi...@mozilla.com>:
Twitter : @JeremiePat <http://twitter.com/JeremiePat>
0 new messages