Update MDN HTML Reference for beginner

[Jeremie Patonnier]

Hi,

The current HTML reference is complete but need to be updated both for
beginner and for accuracy (as suggested in that discussion thread [1])

I suggest to reshape all HTML element articles with the following structure:

1. Remove the "Summary" title (quite useless)
2. Write a quick summary that introduce what the element is made for
(the current summary are quite good it's more about making them consistent
in term of structure across all articles)
3. Add a basic rough example of the element (copy/pastable as much as
possible) with a link to the "How to use the # element" to get more useful
examples.
4. Update the definition table to be real table and make it more
understandable (currently it's just copy pasting from the spec which is
useless in a documentation like MDN). I suggest that we get rid of the 'Tag
omission' section and each time we are making reference to a type of
content, it should be possible to click on it to get the full list of
associated elements.
5. Keep the "Attributes" title (if the element have attributes other
than the globals one)
6. For each attribute, their description should be collapsable and
collapsed by default (we could use the detail/summary element to tag that
behavior). I also suggest that all deprecated or non standard attribute are
listed at the end of that list (and possible put in a dedicated sub
section).
7. Advanced examples should be moved to a "How to use the # element"
article
8. Keep the spec table
9. Keep the browser compat table and stuff below it
10. A see also section should always be at the end with at minimum a
link to the "How to use the HTML # element" article (more links are allowed
off course)

All those change will require some development work, but here is an example
of what such a page could looks like:

- https://www.diigo.com/item/image/58ljs/umbx
- Compare with the original:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a

So the question is: What do you think?

[1] https://groups.google.com/d/msg/mozilla.dev.mdc/yodRPYhXshQ/MYud2c6zowkJ

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

[Jean-Yves Perrier]

On 07/04/2015 16:19, Jeremie Patonnier wrote:
> I suggest to reshape all HTML element articles with the following structure:
>
> 1. Remove the "Summary" title (quite useless)

Yes, I think we are now removing them everywhere.

> 2. Write a quick summary that introduce what the element is made for
> (the current summary are quite good it's more about making them consistent
> in term of structure across all articles)
> 3. Add a basic rough example of the element (copy/pastable as much as
> possible) with a link to the "How to use the # element" to get more useful
> examples.
> 4. Update the definition table to be real table and make it more
> understandable (currently it's just copy pasting from the spec which is
> useless in a documentation like MDN). I suggest that we get rid of the 'Tag
> omission' section and each time we are making reference to a type of
> content, it should be possible to click on it to get the full list of
> associated elements.

I do agree, these tables are old (they were the first ones created) and
a bit outdated (in content too).

> 5. Keep the "Attributes" title (if the element have attributes other
> than the globals one)

A small point here, we have a macro to create an anchor for the
attribute name and a lot of pages link directly to the attribute in the
element page (as they have no direct page, this make a deeplink)

Do we want to add the list of attributes in alphabetical order in the
sidebar?

> 6. For each attribute, their description should be collapsable and
> collapsed by default (we could use the detail/summary element to tag that
> behavior).

I don't know for this one. We should likely do a test page or two (a
short article and a long one) to see if it is nice or not.

I'm not convinced by the collapsed version of them though.

> I also suggest that all deprecated or non standard attribute are
> listed at the end of that list (and possible put in a dedicated sub
> section).

+1000, we have to be sure the HTMLRef macro has to list all attributes
in alphabetic order in the QL (it doesn't right now)

> 7. Advanced examples should be moved to a "How to use the # element"
> article

I think it is a good idea, but I would like to see a concrete example
before having a definite opinion. I'm wondering about the structure of
this article.

> 8. Keep the spec table
> 9. Keep the browser compat table and stuff below it
> 10. A see also section should always be at the end with at minimum a
> link to the "How to use the HTML # element" article (more links are allowed
> off course)

OK with 8-9-10

>
> All those change will require some development work, but here is an example
> of what such a page could looks like:
>
> - https://www.diigo.com/item/image/58ljs/umbx
> - Compare with the original:
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
>
> So the question is: What do you think?
>
> [1] https://groups.google.com/d/msg/mozilla.dev.mdc/yodRPYhXshQ/MYud2c6zowkJ
>
> Best,


--

Jean-Yves Perrier
Senior Technical Writer / Mozilla Developer Network

[Chris Mills]

> On 7 Apr 2015, at 18:01, Jean-Yves Perrier <jype...@gmail.com> wrote:
>
> On 07/04/2015 16:19, Jeremie Patonnier wrote:
>> I suggest to reshape all HTML element articles with the following structure:
>>
>> 1. Remove the "Summary" title (quite useless)
> Yes, I think we are now removing them everywhere.

+1, totally agree.

>> 2. Write a quick summary that introduce what the element is made for
>> (the current summary are quite good it's more about making them consistent
>> in term of structure across all articles)

Kind of like the “Concepts” section in API landing pages really, in purpose. Don’t show code, just explain the broad purpose. If there are a lot of details to cover, then just cover it at a high level, and defer the lower level details to the “Using…” article.

>> 3. Add a basic rough example of the element (copy/pastable as much as
>> possible) with a link to the "How to use the # element" to get more useful
>> examples.

Yup, sounds fine. Although “How to use…” -> “Using…” for consistency with the API “Using…” articles?

>> 4. Update the definition table to be real table and make it more
>> understandable (currently it's just copy pasting from the spec which is
>> useless in a documentation like MDN). I suggest that we get rid of the 'Tag
>> omission' section and each time we are making reference to a type of
>> content, it should be possible to click on it to get the full list of
>> associated elements.
> I do agree, these tables are old (they were the first ones created) and
> a bit outdated (in content too).

Yup, I agree with this too. Tag omission is mostly pointless, as it is at least implied by the examples. I still think we should put the definition table lower down the page, as it is less useful to most people than the simple example, imo.

>
>
>> 5. Keep the "Attributes" title (if the element have attributes other
>> than the globals one)

I agree, although it seems to me that the wording should be different for the global attributes. Do any elements NOT include them? Instead of "This element includes the global attributes.” We could say “In addition to the global attributes, this elements includes the attributes listed below.” or something.

> A small point here, we have a macro to create an anchor for the
> attribute name and a lot of pages link directly to the attribute in the
> element page (as they have no direct page, this make a deeplink)
>
> Do we want to add the list of attributes in alphabetical order in the
> sidebar?

I think this would be more useful than the current big list of elements shown in Jeremie’s example page. Are they a predefined list of related elements?

>> 6. For each attribute, their description should be collapsable and
>> collapsed by default (we could use the detail/summary element to tag that
>> behavior).
> I don't know for this one. We should likely do a test page or two (a
> short article and a long one) to see if it is nice or not.
>
> I'm not convinced by the collapsed version of them though.

Nah, me neither. I don’t really see the point of this. In the same manner as interfaces and their properties, could we consider having separate pages for the attributes, or perhaps just for the ones that have longer extended descriptions that we might not want to dump onto the element page?

>> I also suggest that all deprecated or non standard attribute are
>> listed at the end of that list (and possible put in a dedicated sub
>> section).
> +1000, we have to be sure the HTMLRef macro has to list all attributes
> in alphabetic order in the QL (it doesn't right now)

Yes. I usually put obsolete interfaces/properties/methods in separate sections below the main list, in API pages.

>
>> 7. Advanced examples should be moved to a "How to use the # element"
>> article
> I think it is a good idea, but I would like to see a concrete example
> before having a definite opinion. I'm wondering about the structure of
> this article.

The article structure could differ depending on the element in question. For example a “Using the <a> element” article could be relatively short and succinct and contain some best practices like “best practices for writing link text”, whereas a “Using the <input> element” would be huge and long and sprawling and technical and probably need a separate article for each input type=“” (we have one already, right?).

Then in the opposite direction, there are certain elements that are (nearly) always used together, so would probably benefit in sharing a “Using…” article. Examples include legend and fieldset, and table/td/tr/th (tbody/thead/tfoot perhaps could have a separate article to cover them together)

I think we should have a set of guidelines covering recommended content, but not set the overall structure in stone. I also think we should write 2-3 concrete examples to illustrate typical archetypes, as described above.

>> 8. Keep the spec table
>> 9. Keep the browser compat table and stuff below it
>> 10. A see also section should always be at the end with at minimum a
>> link to the "How to use the HTML # element" article (more links are allowed
>> off course)
> OK with 8-9-10

Yes, agreed.

>
>
>>
>> All those change will require some development work, but here is an example
>> of what such a page could looks like:
>>
>> - https://www.diigo.com/item/image/58ljs/umbx
>> - Compare with the original:
>> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
>>
>> So the question is: What do you think?
>>
>> [1] https://groups.google.com/d/msg/mozilla.dev.mdc/yodRPYhXshQ/MYud2c6zowkJ
>>
>> Best,
>
>
> --
> Jean-Yves Perrier
> Senior Technical Writer / Mozilla Developer Network
>
>

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

[Jeremie Patonnier]

Hi!

2015-04-07 19:01 GMT+02:00 Jean-Yves Perrier <jype...@gmail.com>:

> On 07/04/2015 16:19, Jeremie Patonnier wrote:
> > 5. Keep the "Attributes" title (if the element have attributes other
> > than the globals one)

> A small point here, we have a macro to create an anchor for the
> attribute name and a lot of pages link directly to the attribute in the
> element page (as they have no direct page, this make a deeplink)
>

Ah right, well spotted. I checked the macro (htmlattrxref and htmlattrdef),
the suggested change won't affect their behavior.

> Do we want to add the list of attributes in alphabetical order in the
> sidebar?
>

No opinion on that but it sounds like a good idea.

> > 6. For each attribute, their description should be collapsable and
> > collapsed by default (we could use the detail/summary element to tag
> that
> > behavior).
> I don't know for this one. We should likely do a test page or two (a
> short article and a long one) to see if it is nice or not.
>

I'll start that today.

> I'm not convinced by the collapsed version of them though.
>

Currently, the content of attribute can be very long on some pages and make
it hard to find the related information quickly (as most of the time people
are looking for information about a specific attribute). Collapsed by
default make the page easier to parse and help the user focus on the
attribute he has opened.

> > I also suggest that all deprecated or non standard attribute are
> > listed at the end of that list (and possible put in a dedicated sub
> > section).
> +1000, we have to be sure the HTMLRef macro has to list all attributes
> in alphabetic order in the QL (it doesn't right now)
>

I will do some test and see how the macro react in order to see what's need
to be changed in it.

> > 7. Advanced examples should be moved to a "How to use the # element"
> > article
> I think it is a good idea, but I would like to see a concrete example
> before having a definite opinion. I'm wondering about the structure of
> this article.
>

More about this on this discussion thread:
https://groups.google.com/d/msg/mozilla.dev.mdc/JZ4I4HaKSxQ/I1NcH3Y_jjoJ

> All those change will require some development work, but here is an
> example
> > of what such a page could looks like:
> >
> > - https://www.diigo.com/item/image/58ljs/umbx
> > - Compare with the original:
> > https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
>

[Jeremie Patonnier]

Hi!

Here are some experiments to reshape HTML Element articles:

- https://developer.mozilla.org/en-US/docs/User:Jeremie/a (long article)
- https://developer.mozilla.org/en-US/docs/User:Jeremie/span (short
article)

I'm still convince that collapsing of attribute definitions would be a nice
improvement but it require some serious dev work to handle it smoothly
(especially, it needs some appropriate styling, a way to handle collapsable
elements with the editor, and the ability to open a collapsed element when
an attribut is target through URL)

So all those constrain tell me we should forget about collapsing for now.

IMO, the big win is the short example at the top of the page just after the
first paragraph.

What do you think?

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