"How to use HTML element" articles on MDN

[Jeremie Patonnier]

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>

[Chris Mills]

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
* 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]

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)

[Chris Mills]

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

Yup, agreed.

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

I was thinking just a link to the latest spec might be nice, but yeah, probably not needed if the main landing page has the nice detailed spec info, as per usual.

[Jeremie Patonnier]

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 ?

Best,
--
Jeremie
.............................
Web : http://jeremie.patonnier.net

Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Chris Mills]

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.

[Jeremie Patonnier]

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)

Best,
--
Jeremie
.............................
Web : http://jeremie.patonnier.net

Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Chris Mills]

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

Ok, cool. I think your reasoning is sound. I don’t think a bit of repetition (e.g. with <source>, and common attributes) in the different articles will hurt, especially if some of them have slightly different uses in the different cases.

>
> > • 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)

Plus you can use specific wording to say that we are not recommending these libraries over others, just providing some examples to illustrate our points.

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

Any kind of split (part 1 and part 2, etc,) would be somewhat arbitrary. We could perhaps split it into “Common text level semantics” and “Uncommon text level semantics”, but the placement call would be tricky for some of them ;-)

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

Ok, sounds cool.

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

Cool - let me know what you want help with, and I’ll be there!

[Jeremie Patonnier]

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>

[Jean-Yves Perrier]

Hi!

Globally, I like it. There are likely some details here or there (like
the look of the box, or do we want it to be in a JSON DB that is much
easier to maintain)

I have a big concern about navigability.

When we are on the "Using the <abbr> element" page, we have no way to
reach other HTML element.

The Zone sidebar is not very useful there. Basically, if <abbr> is not
what we were looking for, the user is stuck (and people, especially
beginners, don't hit the back button).

Shouldn't we have the same sidebar as the regular HTML pages instead?

--
Jean-Yves

Jean-Yves Perrier
Senior Technical Writer / Mozilla Developer Network

[Florian Scholz]

Hi

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

If I am a reader that has exactly this intention (learning about HTML
tag x), I now have to decide whether I will go to the HTML elements
guide or the HTML element reference. Both offer categories and both
offer information about how to use element x.
Now, the reference contains an information table, a spec table, and a
compat table in addition, while the Using xx element page contains
richer text and samples. Personally, it is not clear to me, why we need
this documentation split across two pages/areas.

Learning in an isolated way about element x can happen in one source in
my opinion. Enriching the existing abbr reference page looks possible to
me with the information from the "Using the abbr element".

Serving the pathway "I want to learn about tag x" looks already done by
the reference in my eyes and we could be looking into how to serve it
there better if it is not good enough.

Now, I know there are updates planned to the reference pages, too. But
if I look at the updated <abbr> reference pages it is almost useless to
me now. It only has the pure information/data. Sure, I can click on the
little link "Using the <abbr> element", but then I have to start from
zero again. I am again introduced to the element, I get an example and
so forth. Why not having a single page and reading flow?

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

These are very nice pathways to learn about different html elements and
their purposes. I look forward to see more of this.
The learning pathways here are completely different and do not interfere
with the reference pathway (learn element x) at all. Putting elements
into context and categories and then coming up with an overall pathway
to learn the contexts and categories is a good way to shape a curriculum
around learning HTML in my opinion.

Florian.

--
Florian Scholz
Technical Writer
Mozilla Developer Network

[Jeremie Patonnier]

Hi Jean-Yves.

2015-04-14 14:59 GMT+02:00 Jean-Yves Perrier <jype...@gmail.com>:

> Hi!
>
> Globally, I like it. There are likely some details here or there (like
> the look of the box, or do we want it to be in a JSON DB that is much
> easier to maintain)
>

https://bugzilla.mozilla.org/show_bug.cgi?id=1154283 ;)

> I have a big concern about navigability.
>
> When we are on the "Using the <abbr> element" page, we have no way to
> reach other HTML element.
>
> The Zone sidebar is not very useful there. Basically, if <abbr> is not
> what we were looking for, the user is stuck (and people, especially
> beginners, don't hit the back button).
>
> Shouldn't we have the same sidebar as the regular HTML pages instead?
>

Mmmh, yes, right, this is something that would be more interesting in many
ways.

--
Jeremie
.............................
Web : http://jeremie.patonnier.net

Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Jeremie Patonnier]

Hi!

2015-04-14 15:57 GMT+02:00 Florian Scholz <fsc...@mozilla.com>:

> Hi
>
> 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.
>>
> If I am a reader that has exactly this intention (learning about HTML tag
> x), I now have to decide whether I will go to the HTML elements guide or
> the HTML element reference. Both offer categories and both offer
> information about how to use element x.
>

Actually there is no need to decide, both article Reference vs Learn are
linked and it is not really important where you are starting. The fact that
both article offer information about HOW to use the element is a flow that
needs to be fixed. Reference address the needs of average to skilled
developper and should just provide the relevant technical information.
Learn address the needs of beginners to average developper and is only
usage oriented, we avoid the technical details to focus on how it should be
used. So basically you want the technical part (spec, compatibility,
content relationship), go to the reference, if you just want to use it go
to the learn page.

To complete that I get some feedback by a few developer that found the
current HTML reference quite clumsy and look for something simpler and more
straightforward.

> Now, the reference contains an information table, a spec table, and a
> compat table in addition,

It shouldn't be "in addition".

> while the Using xx element page contains richer text and samples.
> Personally, it is not clear to me, why we need this documentation split
> across two pages/areas.
>

The abbr example is certainly not the most accurate as it's one of the
simplest element to use in HTML. I agree that in that specific case it
looks a bit artificial. But for example, if you go to <a> or <button>
having every things (tech and usage) both in the same page make things very
hard to read with a long, barely usable page.

> Learning in an isolated way about element x can happen in one source in my
> opinion. Enriching the existing abbr reference page looks possible to me
> with the information from the "Using the abbr element".
>
> Serving the pathway "I want to learn about tag x" looks already done by
> the reference in my eyes and we could be looking into how to serve it there
> better if it is not good enough.
>

Absolutely, suggestion welcome. Do you have more opinion about this:
https://groups.google.com/d/msg/mozilla.dev.mdc/JZ4I4HaKSxQ/jE9m5pygzP4J

> Now, I know there are updates planned to the reference pages, too.

It's not set in stone but if no one tell me otherwise I plan to get into it
quite hard (see my proposal here:
https://groups.google.com/d/msg/mozilla.dev.mdc/chFlz4GBm4E/Xmt9jICW9A8J)

> But if I look at the updated <abbr> reference pages it is almost useless
> to me now.

In term of content, the only things that really change is that I moved the
note about plural and internationalisation into the "Using the <abbr>
element". Otherwise there is no change in the relevant content (I just
remove or move some useless details). So telling the reference page is now
almost useless seams a bit strong. Could you detail how the change affect
the usability for you? That could be useful to improve page layout.

> It only has the pure information/data. Sure, I can click on the little
> link "Using the <abbr> element", but then I have to start from zero again.
> I am again introduced to the element, I get an example and so forth. Why
> not having a single page and reading flow?

In that very specific case, I tend to agree that it looks a bit overkill,
which is not necessary as easy with more complexe element. But that doesn't
sounds like some real use case (I'm possibly amazingly wrong on that point)
and I would love to hear more about that. I'll possibly do another try with
a more complexe element in order to see how that affect the actual
usability of the reference (for the better or the worst).

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.
>>
> These are very nice pathways to learn about different html elements and
> their purposes. I look forward to see more of this.
>

That the main plan ;)

However there is many use case where a single HTML element do the trick.
For example the difference between "How to add images to a web page" and
"Using the <img> tag" is essentially a semantic choice. The only technical
difference is if we want to go into clumsy possibility such as using the
<object> or <iframe> element instead of the <img> one, or if we want to
cover css background or inline svg (which both deserve an article of their
own as they are very complexe features to handle). That say, I agree that
making such semantic difference is possibly how it should be done and get
rid of "Using the X element" once and for all. Mmmh... I definitely need to
think more about that.

> The learning pathways here are completely different and do not interfere
> with the reference pathway (learn element x) at all. Putting elements into
> context and categories and then coming up with an overall pathway to learn
> the contexts and categories is a good way to shape a curriculum around
> learning HTML in my opinion.

Possibly, but I would love to here more about you ideas in that area based
on this:
https://groups.google.com/d/msg/mozilla.dev.mdc/JZ4I4HaKSxQ/jE9m5pygzP4J

Best,

[Andrew Pfeiffer]

Jeremie,

Thank you for sharing the progress with us. It really does look
exciting and I'm looking forward to seeing what the future is
bringing!

As someone still learning myself, I must say I do like Florian's idea
of keeping one page about each element rather than two. I would think
there must be some way to merge the good ideas from the Learning Area
page with the reference page.

I suggest we can do it by keeping everything plenty concise and also
giving some thought to how we should order everything on the reference
pages, so the experts can find what they need fast without confusing
beginners who have read our excellent introductory material. If
necessary, we could even write an article explaining how to use our
HTML reference.

Otherwise, I really like how it looks!
Andrew

On Tue, Apr 14, 2015 at 9:41 AM, <dev-mdc...@lists.mozilla.org> wrote:
> Send dev-mdc mailing list submissions to
> dev...@lists.mozilla.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
> https://lists.mozilla.org/listinfo/dev-mdc
> or, via email, send a message with subject or body 'help' to
> dev-mdc...@lists.mozilla.org
>
> You can reach the person managing the list at
> dev-md...@lists.mozilla.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of dev-mdc digest..."
>
>
> Today's Topics:
>
> 1. Re: "How to use HTML element" articles on MDN (Jeremie Patonnier)
> 2. Re: "How to use HTML element" articles on MDN (Jean-Yves Perrier)
> 3. Re: "How to use HTML element" articles on MDN (Florian Scholz)
> 4. Re: "How to use HTML element" articles on MDN (Jeremie Patonnier)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Tue, 14 Apr 2015 14:25:14 +0200
> From: Jeremie Patonnier <jeremie....@gmail.com>
> To: Chris Mills <cmi...@mozilla.com>
> Cc: dev-mdc <dev...@lists.mozilla.org>, Mozilla Webmaker list
> <webm...@lists.mozilla.org>
> Subject: Re: "How to use HTML element" articles on MDN
> Message-ID:
> <CAEi838nifPWgRWRUOmVxbGgB6kEqPAS3EX5=-nGtSEL...@mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8

>
> 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
>
> 2015-04-09 12:32 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
>
>>
>> > 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

>> Ok, cool. I think your reasoning is sound. I don?t think a bit of

>> repetition (e.g. with <source>, and common attributes) in the different
>> articles will hurt, especially if some of them have slightly different uses
>> in the different cases.
>>
>> >

>> > > ? 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)
>>
>> Plus you can use specific wording to say that we are not recommending
>> these libraries over others, just providing some examples to illustrate our
>> points.
>>
>> >
>> > > 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.
>>
>> Any kind of split (part 1 and part 2, etc,) would be somewhat arbitrary.

>> We could perhaps split it into ?Common text level semantics? and ?Uncommon
>> text level semantics?, but the placement call would be tricky for some of

>> them ;-)
>>
>> >
>> > 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.
>>
>> Ok, sounds cool.
>>
>> >
>> > 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)
>> >
>>

>> Cool - let me know what you want help with, and I?ll be there!

>>
>> > Best,
>> > --
>> > Jeremie
>> > .............................
>> > Web : http://jeremie.patonnier.net
>> > Twitter : @JeremiePat
>>
>>
>
>
> --
> Jeremie
> .............................
> Web : http://jeremie.patonnier.net
> Twitter : @JeremiePat <http://twitter.com/JeremiePat>
>
>

> ------------------------------
>
> Message: 2
> Date: Tue, 14 Apr 2015 13:59:49 +0100
> From: Jean-Yves Perrier <jype...@gmail.com>
> To: dev...@lists.mozilla.org
> Subject: Re: "How to use HTML element" articles on MDN
> Message-ID: <552D0F45...@mozilla.com>
> Content-Type: text/plain; charset=utf-8

>
> Hi!
>
> Globally, I like it. There are likely some details here or there (like
> the look of the box, or do we want it to be in a JSON DB that is much
> easier to maintain)
>

> I have a big concern about navigability.
>
> When we are on the "Using the <abbr> element" page, we have no way to
> reach other HTML element.
>
> The Zone sidebar is not very useful there. Basically, if <abbr> is not
> what we were looking for, the user is stuck (and people, especially
> beginners, don't hit the back button).
>
> Shouldn't we have the same sidebar as the regular HTML pages instead?
>

> --
> Jean-Yves
>
> On 14/04/2015 13:25, Jeremie Patonnier wrote:
>> 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
>>
>> 2015-04-09 12:32 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
>>
>>>> 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

>>> Ok, cool. I think your reasoning is sound. I don?t think a bit of

>>> repetition (e.g. with <source>, and common attributes) in the different
>>> articles will hurt, especially if some of them have slightly different uses
>>> in the different cases.
>>>

>>>>> ? 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)
>>>
>>> Plus you can use specific wording to say that we are not recommending
>>> these libraries over others, just providing some examples to illustrate our
>>> points.
>>>
>>>>> 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.
>>>
>>> Any kind of split (part 1 and part 2, etc,) would be somewhat arbitrary.

>>> We could perhaps split it into ?Common text level semantics? and ?Uncommon
>>> text level semantics?, but the placement call would be tricky for some of

>>> them ;-)
>>>
>>>> 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.
>>>
>>> Ok, sounds cool.
>>>
>>>> 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)

>>> Cool - let me know what you want help with, and I?ll be there!

>>>
>>>> Best,
>>>> --
>>>> Jeremie
>>>> .............................
>>>> Web : http://jeremie.patonnier.net
>>>> Twitter : @JeremiePat
>>>
>>
>
>

> --
> Jean-Yves Perrier
> Senior Technical Writer / Mozilla Developer Network
>
>
>

> ------------------------------
>
> Message: 3
> Date: Tue, 14 Apr 2015 15:57:11 +0200
> From: Florian Scholz <fsc...@mozilla.com>
> To: dev...@lists.mozilla.org
> Subject: Re: "How to use HTML element" articles on MDN
> Message-ID: <552D1CB7...@mozilla.com>
> Content-Type: text/plain; charset=utf-8; format=flowed

>
> Hi
>
>> 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.
> If I am a reader that has exactly this intention (learning about HTML
> tag x), I now have to decide whether I will go to the HTML elements
> guide or the HTML element reference. Both offer categories and both
> offer information about how to use element x.

> Now, the reference contains an information table, a spec table, and a

> compat table in addition, while the Using xx element page contains

> richer text and samples. Personally, it is not clear to me, why we need
> this documentation split across two pages/areas.
>

> Learning in an isolated way about element x can happen in one source in
> my opinion. Enriching the existing abbr reference page looks possible to
> me with the information from the "Using the abbr element".
>
> Serving the pathway "I want to learn about tag x" looks already done by
> the reference in my eyes and we could be looking into how to serve it
> there better if it is not good enough.
>

> Now, I know there are updates planned to the reference pages, too. But

> if I look at the updated <abbr> reference pages it is almost useless to

> me now. It only has the pure information/data. Sure, I can click on the

> little link "Using the <abbr> element", but then I have to start from
> zero again. I am again introduced to the element, I get an example and
> so forth. Why not having a single page and reading flow?
>

>> 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.
> These are very nice pathways to learn about different html elements and
> their purposes. I look forward to see more of this.

> The learning pathways here are completely different and do not interfere
> with the reference pathway (learn element x) at all. Putting elements
> into context and categories and then coming up with an overall pathway
> to learn the contexts and categories is a good way to shape a curriculum
> around learning HTML in my opinion.
>

> Florian.
>
> --
> Florian Scholz
> Technical Writer
> Mozilla Developer Network
>
>
>

> ------------------------------
>
> Message: 4
> Date: Tue, 14 Apr 2015 16:40:18 +0200
> From: Jeremie Patonnier <jeremie....@gmail.com>
> To: Jean-Yves Perrier <jype...@gmail.com>
> Cc: dev-mdc <dev...@lists.mozilla.org>
> Subject: Re: "How to use HTML element" articles on MDN
> Message-ID:
> <CAEi838=aBW7qf6DKFp=yrtJjea7q+Uj_aT...@mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8

>
> Hi Jean-Yves.
>
> 2015-04-14 14:59 GMT+02:00 Jean-Yves Perrier <jype...@gmail.com>:
>
>> Hi!
>>
>> Globally, I like it. There are likely some details here or there (like
>> the look of the box, or do we want it to be in a JSON DB that is much
>> easier to maintain)
>>
>
> https://bugzilla.mozilla.org/show_bug.cgi?id=1154283 ;)
>
>
>> I have a big concern about navigability.
>>
>> When we are on the "Using the <abbr> element" page, we have no way to
>> reach other HTML element.
>>
>> The Zone sidebar is not very useful there. Basically, if <abbr> is not
>> what we were looking for, the user is stuck (and people, especially
>> beginners, don't hit the back button).
>>
>> Shouldn't we have the same sidebar as the regular HTML pages instead?
>>
>
> Mmmh, yes, right, this is something that would be more interesting in many
> ways.

> --
> Jeremie
> .............................
> Web : http://jeremie.patonnier.net
> Twitter : @JeremiePat <http://twitter.com/JeremiePat>
>
>

> ------------------------------
>
> Subject: Digest Footer
>
> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
>
> ------------------------------
>
> End of dev-mdc Digest, Vol 112, Issue 22
> ****************************************

[Chris Mills]

Chiming in a bit late, sorry about that ;-)

I really like how this is going. A few comments on what has been said so far:

1. The elements landing page. This is good, although I would

a. Put the use cases before the categories, as I think the individual element guides seem like the last thing to reach for on a learning pathway

b. Order the use cases themselves in a more logical learning pathway, for example you would create a basic web page first, then you would probably look at text level semantics, then you would probably look at creating a more complex web page structure with <article>, etc.
c. Consider having three sections

- HTML fundamentals (covering use cases such as creating a basic web page, text level semantics, etc.) This stuff would be tightly structured to provide a useful learning pathways
- Advanced HTML use cases (not so tightly structured; go to these as and when you need them). This would include things like internationalization, advanced table structure, navigation menu markup, etc.
- Categories last

2. The guide and reference page. I think these work very well together and actually like the fact that they are separated into two. The reference stuff is more for people who know what the element is for and just want to verify some kind of syntax detail quickly. They don’t want a detailed explanation. the guide is for people who want to learn what the element is for and then have a go at implementing the element themselves. The usefulness of this setup will become more apparent with more complex elements.

I do think we need an elements list in the sidebar of the Learning page, we already have a “back to main menu” link in the breadcrumb trail.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> Doc project Trello board: https://trello.com/b/HAhl54zz/status

[Janet Swisher]

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.

>>>> • Elements that are part of a structure that cannot be break and

>> Ok, cool. I think your reasoning is sound. I don’t think a bit of

>> repetition (e.g. with <source>, and common attributes) in the different
>> articles will hurt, especially if some of them have slightly different uses
>> in the different cases.
>>

>>>> • 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)
>>
>> Plus you can use specific wording to say that we are not recommending
>> these libraries over others, just providing some examples to illustrate our
>> points.
>>
>>>> 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.
>>
>> Any kind of split (part 1 and part 2, etc,) would be somewhat arbitrary.

>> We could perhaps split it into “Common text level semantics” and “Uncommon

>> text level semantics”, but the placement call would be tricky for some of

>> them ;-)
>>
>>> 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.
>>
>> Ok, sounds cool.
>>
>>> 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)

>> Cool - let me know what you want help with, and I’ll be there!

>>
>>> Best,
>>> --
>>> Jeremie
>>> .............................
>>> Web : http://jeremie.patonnier.net
>>> Twitter : @JeremiePat
>>
>

--

Janet Swisher <mailto:jREMOVE...@mozilla.com>
Mozilla Developer Network <https://developer.mozilla.org>
MDN Community Manager

[Jeremie Patonnier]

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>

> Mozilla Developer Network <https://developer.mozilla.org>
> MDN Community Manager
>

--
Jeremie
.............................
Web : http://jeremie.patonnier.net

Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Jeremie Patonnier]

2015-04-14 18:16 GMT+02:00 Chris Mills <cmi...@mozilla.com>:

> Chiming in a bit late, sorry about that ;-)
>
> I really like how this is going. A few comments on what has been said so
> far:
>
> 1. The elements landing page. This is good, although I would
>
> a. Put the use cases before the categories, as I think the individual
> element guides seem like the last thing to reach for on a learning pathway
>

Yes, I'll do this by tomorrow

>
> b. Order the use cases themselves in a more logical learning pathway, for
> example you would create a basic web page first, then you would probably
> look at text level semantics, then you would probably look at creating a
> more complex web page structure with <article>, etc.
>

Right, that was just a "let's make a list" thing, but I agree with that :)

> c. Consider having three sections
>
> - HTML fundamentals (covering use cases such as creating a basic web page,
> text level semantics, etc.) This stuff would be tightly structured to
> provide a useful learning pathways
> - Advanced HTML use cases (not so tightly structured; go to these as and
> when you need them). This would include things like internationalization,
> advanced table structure, navigation menu markup, etc.
> - Categories last
>

Regarding the comments from Florian and Janet, I thing we need more though
on that, I will come with a new proposal (but possibly for next week rather
than tomorrow ;)

2. The guide and reference page. I think these work very well together and
> actually like the fact that they are separated into two. The reference
> stuff is more for people who know what the element is for and just want to
> verify some kind of syntax detail quickly. They don’t want a detailed
> explanation. the guide is for people who want to learn what the element is
> for and then have a go at implementing the element themselves. The
> usefulness of this setup will become more apparent with more complex
> elements.
>

Yes, I think we all agree on this. The important things, as Janet pointed
out, is to work on the semantic to provide a more task oriented approach
rather than just "How to use X" (but I suspect it will not change what will
be done underneath).

I do think we need an elements list in the sidebar of the Learning page, we
> already have a “back to main menu” link in the breadcrumb trail.
>

Let's see once we will get something a bit more task oriented than now.

Best

[Karl Dubost]

Le 14 avr. 2015 à 22:57, Florian Scholz <fsc...@mozilla.com> a écrit :
> If I am a reader that has exactly this intention (learning about HTML tag x), I now have to decide whether I will go to the HTML elements guide or the HTML element reference. Both offer categories and both offer information about how to use element x.

Should the two pages (spec, guide) have something along (or a better UI proposal ^_^ )

[Implementing abbr] [Using abbr]

So when you are on one page you can switch to the other easily.


--
Karl Dubost, Mozilla
http://www.la-grange.net/karl/moz

[Jean-Yves Perrier]

Hi!

Ha! I think Janet and Florian nailed the problem down.

The current example page "How to use the <abbr> element" is not a
tutorial. It is a second reference page. That's why navigation cannot be
defined logically.

This page should really be "How to use abbreviations and acronyms in an
HTML page". It should start by explaining what abbreviations and
acronyms are and then by showing how to mark these up (with the <abbr>
element), which is not the current structure (though it should be easy
to adapt).

Also notes like "In HTML4 there was the acronym element, but now in
HTML5 only use <abbr>" (I paraphrased) really show that the article was
(unconsciously) thought as a reference . This information has nothing to
do in a tutorial page, beside a "don't use the deprecated <acronym>
element", with the gory details hidden in the <acronym> element
reference page : we are teaching today's Web not its history. The HTML
reference has this information.


To solve the navigation problem, we can see now that there won't be a
1:1 relationship between these pages and elements in the reference.

E.g. We will not have a "How to use <td> element", but "How to add a
table to my document" that will start with the basic <table> structure
and go forward to explain things more complex like <colgroup> and
<rowgroup> or <caption>. We may even more specific pages if it proves
too long.At some point we alson link to a "styling tables in CSS" article.

We will have "How to add ruby to some text" to explain bopomofo and
furigana, "How to cite and quote text", "How to insert code snippets in
a page", "How to display a dialog between several people", "How to add a
video", "How to add an image"… [The grouping we did in Berlin should
help a lot to identify them there.]

So I think, the next step is to list these articles, because that way we
can also see what there dependencies are. E.g. Most of the articles will
assume the reader will know the difference between the <head> and <body>
area of an article, so this dependencies should be listed for each
article, in the top box like we did for the first learning pathway.

As the naming of the page will not give it naturally, we should also
list which elements are described in the article, so that we can check
if we have the required coverage.

The navigation will become natural: the tutorial articles will have a
sidebar allowing them to navigate to other How to articles (and to the
top of the reference), the HTML elements will have the current sidebar
(likely improved) and links to the tutorials (one or several) that makes
use of the specific element.

We can see it from a different perspective; imagine we are dealing with
CSS, we will not create "How to use the animation-name property" but
"How to use CSS Animations" or "How to use the flex-basis property" but
"How to use flexible boxes". That's the same here.

It also prevents another problem: emptying the reference from meaningful
content. We need to keep there all the information useful for somebody
who comes direct to the element. We don't need to have examples that
shows the element in complex context, as this is covered by the "How
to", but we need to have enough examples that all its syntax have a
basic usage (think of <meta> where not all attributes are used at the
same time. If we know the correct element and what we want to do, we
shouldn't have to navigate out to the tutorial to get the necessary
information.

Hope it helps
--
Jean-Yves

>> 2015-04-09 12:32 GMT+02:00 Chris Mills <cmi...@mozilla.com>:
>>
>>>> On 9 Apr 2015, at 10:25, Jeremie Patonnier
>>>> <jeremie....@gmail.com>

>>>> --
>>>> Jeremie
>>>> .............................
>>>> Web : http://jeremie.patonnier.net
>>>> Twitter : @JeremiePat
>>>
>>
>

[Jeremie Patonnier]

Hi,

I basically agreed with Jean-Yves, modulo a few details below :)

2015-04-15 13:54 GMT+02:00 Jean-Yves Perrier <jype...@gmail.com>:

> Hi!
>
> Ha! I think Janet and Florian nailed the problem down.
>
> The current example page "How to use the <abbr> element" is not a
> tutorial. It is a second reference page. That's why navigation cannot be
> defined logically.
>
> This page should really be "How to use abbreviations and acronyms in an
> HTML page". It should start by explaining what abbreviations and
> acronyms are and then by showing how to mark these up (with the <abbr>
> element), which is not the current structure (though it should be easy
> to adapt).
>
> Also notes like "In HTML4 there was the acronym element, but now in
> HTML5 only use <abbr>" (I paraphrased) really show that the article was
> (unconsciously) thought as a reference . This information has nothing to
> do in a tutorial page, beside a "don't use the deprecated <acronym>
> element", with the gory details hidden in the <acronym> element
> reference page : we are teaching today's Web not its history. The HTML
> reference has this information.
>

I slightly disagree on that. People does not live in a closed bubble and
there are plenty of other tutorial out there. Because of that it's really
important to point out old practices that are now considered bad practice
and why. But yes, this has to be rephrase in a way that appear less
technical.

> To solve the navigation problem, we can see now that there won't be a
> 1:1 relationship between these pages and elements in the reference.
>
> E.g. We will not have a "How to use <td> element", but "How to add a
> table to my document" that will start with the basic <table> structure
> and go forward to explain things more complex like <colgroup> and
> <rowgroup> or <caption>. We may even more specific pages if it proves
> too long.At some point we alson link to a "styling tables in CSS" article.
>
> We will have "How to add ruby to some text" to explain bopomofo and
> furigana, "How to cite and quote text", "How to insert code snippets in
> a page", "How to display a dialog between several people", "How to add a
> video", "How to add an image"… [The grouping we did in Berlin should
> help a lot to identify them there.]
>
> So I think, the next step is to list these articles, because that way we
> can also see what there dependencies are.

Currently on it-. It should be done today :)

> E.g. Most of the articles will
> assume the reader will know the difference between the <head> and <body>
> area of an article, so this dependencies should be listed for each
> article, in the top box like we did for the first learning pathway.
>

Yes, we will follow that a structure very close to that:
https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web

> As the naming of the page will not give it naturally, we should also
> list which elements are described in the article, so that we can check
> if we have the required coverage.
>
> The navigation will become natural: the tutorial articles will have a
> sidebar allowing them to navigate to other How to articles (and to the
> top of the reference),

Mmmh it's to early to be sure about that, but, yes, ultimately we want to
do something more or less like that. The only difficult point is that all
those article will almost never follow a straight line of learning.

> the HTML elements will have the current sidebar
> (likely improved) and links to the tutorials (one or several) that makes
> use of the specific element.
>
> We can see it from a different perspective; imagine we are dealing with
> CSS, we will not create "How to use the animation-name property" but
> "How to use CSS Animations" or "How to use the flex-basis property" but
> "How to use flexible boxes". That's the same here.
>

More likely: "How to layout a blog page", "How to design loading button",
etc. ;)

> It also prevents another problem: emptying the reference from meaningful
> content. We need to keep there all the information useful for somebody
> who comes direct to the element.

Which will need a full discussion on its own as "useful information" is a
highly debatable topic ;) see:
https://groups.google.com/d/msg/mozilla.dev.mdc/chFlz4GBm4E/Xmt9jICW9A8J

> We don't need to have examples that
> shows the element in complex context, as this is covered by the "How
> to", but we need to have enough examples that all its syntax have a
> basic usage (think of <meta> where not all attributes are used at the
> same time. If we know the correct element and what we want to do, we
> shouldn't have to navigate out to the tutorial to get the necessary
> information.
>

Best :)

--
Jeremie
.............................
Web : http://jeremie.patonnier.net

Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Sebastian Zartner]

On Wednesday, April 15, 2015 at 2:51:48 PM UTC+2, Jeremie Patonnier wrote:
> > Also notes like "In HTML4 there was the acronym element, but now in
> > HTML5 only use <abbr>" (I paraphrased) really show that the article was
> > (unconsciously) thought as a reference . This information has nothing to
> > do in a tutorial page, beside a "don't use the deprecated <acronym>
> > element", with the gory details hidden in the <acronym> element
> > reference page : we are teaching today's Web not its history. The HTML
> > reference has this information.
> >
>
> I slightly disagree on that. People does not live in a closed bubble and
> there are plenty of other tutorial out there. Because of that it's really
> important to point out old practices that are now considered bad practice
> and why. But yes, this has to be rephrase in a way that appear less
> technical.

This depends on the audience you want to reach. As you say it's HTML for beginners. Beginners don't know about the deprecated elements and shouldn't be bothered with them.

Non-the-less documenting deprecated elements and the reasons why they are not used anymore is important, though I believe it might be better to do so in separate articles.

> > As the naming of the page will not give it naturally, we should also
> > list which elements are described in the article, so that we can check
> > if we have the required coverage.
> >
> > The navigation will become natural: the tutorial articles will have a
> > sidebar allowing them to navigate to other How to articles (and to the
> > top of the reference),
>
>
> Mmmh it's to early to be sure about that, but, yes, ultimately we want to
> do something more or less like that. The only difficult point is that all
> those article will almost never follow a straight line of learning.

A beginner may not need to follow a straight line. Of course all need to know about the basic structure of a page, though then the needs of the people diverge. They do not necessarily need to learn about tables first when they want to create a blog website for example. So I don't get what's the 'difficult point' in this regard.
It should be made very easy for the readers to switch between different tutorial articles. And I agree with Jean-Yves that the sidebar can help here.
What may be difficult is how to display those articles there.

> > the HTML elements will have the current sidebar
> > (likely improved) and links to the tutorials (one or several) that makes
> > use of the specific element.
> >
> > We can see it from a different perspective; imagine we are dealing with
> > CSS, we will not create "How to use the animation-name property" but
> > "How to use CSS Animations" or "How to use the flex-basis property" but
> > "How to use flexible boxes". That's the same here.
> >
>
> More likely: "How to layout a blog page", "How to design loading button",
> etc. ;)

'CSS Animations' is definitely still too technical, though on the other hand 'How to design a loading button' is too specific. So it should be something in between like 'How to do animations'.
Also 'How to layout a blog page' covers a too specific use case. And though it's too broad for only covering flexible boxes.

But there could be multiple 'How to ...' pages redirecting to the same artile.

Sebastian

[Karl Dubost]

Le 15 avr. 2015 à 20:54, Jean-Yves Perrier <jype...@gmail.com> a écrit :
> This page should really be "How to use abbreviations and acronyms in an
> HTML page".

Yes. Rule of thumbs. Forget about the tag names in tutorials.
Or more exactly, it's not about learning HTML, but about describing documents (aka semantics) and to do that, we use HTML.

> It should start by explaining what abbreviations and acronyms are

My dream comes true ;). I'm due to offer a round of drinks next time I meet people working on this.

> E.g. We will not have a "How to use <td> element", but "How to add a
> table to my document"

table: "a set of facts or figures systematically displayed, especially in columns."
Or maybe something along "How to express tabular data in a document"(?)

> We will have "How to add ruby to some text" to explain bopomofo and
> furigana,

I wonder if ruby is known outside of technical people. Having a discussion here in the Japanese office right now. In Japan, for example, people will most likely use furigana. In Taiwan I don't know. Maybe there's another way of calling these subscript/superscript annotations. Oops. Maybe I just did.

> "How to cite and quote text",

I would separate quoting (a text insertion that you can point to a reference) and citing (aka giving the title reference and data about a source).

> "How to insert code snippets in a page",
> "How to display a dialog between several people",

How do describe a dialog between several people. (?)

> "How to add a video",
> "How to add an image"… [The grouping we did in Berlin should
> help a lot to identify them there.]

Nice work in progress!!!

[Jeremie Patonnier]

Hi :)

Based on all your feedback , I totally reshape the landing page for
learning HTML.

- https://developer.mozilla.org/en-US/Learn/HTML/Element

It task oriented only, with two level: Common use cases and Uncommon (or
advanced) use cases. The various use case I listed cover 90% of the
elements (if not 100%). But feel free to add more use cases that could be
interesting.

I still wonder how to split down the "text level semantic bucket" but it's
not urgent.

I also completely reshape the example article about the <abbr> element

- https://developer.mozilla.org/en-US/Learn/HTML/Element/abbr

It's now all about abbreviation (what it is and how to write for it, how to
handle them with HTML, and a practical exercice) and not just about
describing the HTML <abbr> element.

I think this is more in line with all we discuss previously. What do you
think?

Best,
Jeremie

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status
>

[Eric Shepherd]

Jeremie Patonnier wrote:
> It's now all about abbreviation (what it is and how to write for it, how to
> handle them with HTML, and a practical exercice) and not just about
> describing the HTML<abbr> element.

On a practical level, making people do eight basically identical things
to complete an exercise is going to bore them. For an element as simple
as <abbr>, you should only have one or two abbreviations to mark up in
the exercise. Beyond that, it's just punishment. :D

--

Eric Shepherd
Senior Technical Writer
Mozilla <https://www.mozilla.org/>
Blog: http://www.bitstampede.com/
Twitter: http://twitter.com/sheppy

[Jeremie Patonnier]

Hi,

No extra comment, that sounds good :)
Ok, I'll go to update some meta documentation to get into active writing.

I keep in mind the issue about navigation. Because of that I'm hesitating
between hosting those article under /learn/HTML (my favorite choice) or
under /docs/Web/HTML/Guide. Any opinion? (obviously, that does not prevent
us to start writing as it will be just a matter of moving page in the end)

2015-04-16 16:35 GMT+02:00 Eric Shepherd <eshe...@mozilla.com>:

> On a practical level, making people do eight basically identical things to
> complete an exercise is going to bore them. For an element as simple as
> <abbr>, you should only have one or two abbreviations to mark up in the
> exercise. Beyond that, it's just punishment. :D
>

Ah, ah, right, I was a bit too exited by creating such exercice :P I'm
gonna make it simpler ;)

Best,

[Julien Sphinx]

Hello,

I would go for the /docs/Web/HTML/Guide option.
Actually, I've been thinking that we could reach a "homogeneous" state where we can have

/docs/Web/X/
/docs/Web/X/Reference
/docs/Web/X/Guide

For all three sections: HTML, JS and CSS.
That would be great (the reader would know what to find where etc.).

As we discussed earlier, the edge between a Guide and the Learning Area can be a bit thin/ambiguous so I'd welcome more opinions on that ;)

My 2 cents :)
Julien / Sphinx

----------------------------------------
> From: jeremie....@gmail.com
> Date: Mon, 20 Apr 2015 11:51:14 +0200

> Subject: Re: "How to use HTML element" articles on MDN

> To: eshe...@mozilla.com
> CC: kdu...@mozilla.com; jype...@gmail.com; dev...@lists.mozilla.org

[Eric Shepherd]

Julien Sphinx wrote:
> > I keep in mind the issue about navigation. Because of that I'm hesitating
> > between hosting those article under /learn/HTML (my favorite choice) or
> > under /docs/Web/HTML/Guide. Any opinion? (obviously, that does not prevent
> > us to start writing as it will be just a matter of moving page in the end)

I personally favor putting the material under docs/Web/HTML/Guide. This
will let us have the learning area material separated using
auto-generation from tags (or by hand if that's community preference),
and will organizationally keep this stuff in with the other HTML stuff
at a physical and structural level.