853969 - Write documentation for Microdata

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: HTML, defect, P5)

Description

[Tom S]

:: Developer Documentation Request

      Request Type: New Documentation
     Gecko Version: unspecified
 Technical Contact: 

:: Details

We seem to have no documentation for MicroData.

http://www.whatwg.org/specs/web-apps/current-work/multipage/microdata.html

Comment 1

[Duncan McDonald]

I see that this is an older request, but I am willing to work on it. Can you give me an idea of what the scope should be? Summary plus example or a more detailed reprise of the whatwg.org document?

Comment 2

[Jean-Yves Perrier [:teoli]]

Hi!
You'll find examples in the spec, there: https://html.spec.whatwg.org/multipage/microdata.html#introduction-7

The bug where it was implemented is there: https://bugzilla.mozilla.org/show_bug.cgi?id=591467

Basically, you'll need to:
1. create (or update for itemprop and itemscope) a new page for each of the new global attributes:
  a. itemid: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemid
  b. itemprop: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop
  c. itemref: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemref
  d. itemscope: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemscope
  e. itemtype: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemtype
2. Create a generic page about Using the Microdata API that explain and show typical use cases

Comment 3

[Jean-Yves Perrier [:teoli]]

3. You'll need to update their entries there: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes

Comment 4

[Duncan McDonald]

Question on itemid:

https://html.spec.whatwg.org/multipage/microdata.html section "5.2.2 Items" says that "The itemid attribute, if specified, must have a value that is a valid URL potentially surrounded by spaces". But the example shown in "5.1.4 Global identifiers for items" shows the itemid being a URN (itemid="urn:isbn:0-330-34032-8"). A URN is not a URL. 

Can someone clarify this point?

Comment 5

[Duncan McDonald]

Wikipedia says an itemid is a unique identifier, which is consistent with the use of a URN in the Whatwg example. I added a note about that point on the itemid page. Let me know if you object or have other ideas.

Comment 6

[Duncan McDonald]

 Ready for review

Modified pages:
  itemprop: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop
  itemscope: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemscope
  Global_attributes: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
Created new pages:
  itemid: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemid
  itemref: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemref
  itemtype: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemtype
  Microdata DOM API: https://developer.mozilla.org/en-US/docs/Web/API/Microdata_DOM_API
  Microdata (overview page under HTML directory): https://developer.mozilla.org/en-US/docs/Web/HTML/Microdata

Comment 7

[Jean-Yves Perrier [:teoli]]

Hi!

I had a quick glance already, I think there is still a lot of work here (structure of the pages, better linking and contextualisation).

One major problem is I see whole paragraphs that are mere copy of the specs: we must not do this. Not only, because of different licences and autorship (which by itself is a no-go) but also because of a difference audience and therefore vocabulary.

Also for the Microdata DOM API, we will need to create the subpages of Element (1 page/method or property), but I will give you more information in the complete review.

Comment 8

[Duncan McDonald]

Hi Jean-Yves,

Thanks for your feedback. Can you provide some guidance on structure of the pages, linking and contextualisation? I don't know what you mean by contextualisation? For structure I looked at some other documentation and decided that page structure should be something like:

Overview
  Simple example
Subsections on each major aspect
Bigger, more complex example
  HTML
  Summary of structured data in the HTML
  LiveSample of HTML
See Also

I didn't include a formal syntax section since their is formal syntax definition in the standard. Can you recommend a structure?

Second, I did spend time rewording and clarifying the content of the standard (which is really unreadable with lots of circular definitions), but I guess not enough. I will work on it.

I would like to get the rest of the doc in better shape before working on the DOM API.

Comment 9

[desai.meghana1990]

Hi Jean-Yves

Still there is need to Write documentation for Microdata task or it has been completed?

Let me know I am ready to do the same.

Regards,
Meghana

Comment 10

[Duncan McDonald]

Hi Jean-Yves,

I'd like to move this bug forward. Can you give the doc another quick look and provide some additional feedback (see my comments above)?

Thanks,

Duncan