Re: Plan for getting core WPD content sorted out

See my comments inline.

☆*PhistucK*



On Mon, Dec 3, 2012 at 11:37 AM, Chris Mills <cmills@opera.com> wrote:

> On 1 Dec 2012, at 10:53, PhistucK <phistuck@gmail.com> wrote:
>
> > I also think the core stuff should be finalized first. I think it should
> the top priority. That is what everyone (no exception) uses - and it is a
> huge mess.
> >
> > I am working on all of the DOM related reference pages for a while.
> > I am not nearly finished, but I think I am making some good progress.
> > However, I am not really adding content - I am really reorganizing it
> (taking page summaries from manual MSDN listings and removing those
> listings afterward, modernizing the MSDN examples, cleaning up weird 'out'
> MSDN parameters, moving non semantic standards information to the standards
> table and so on).
> > I sometimes add some usage information and compatibility information
> (from caniuse, MDN and such), or write my own summary, but in the majority
> of cases, this does not really happen.
>
> It is another thing that needs sorting out in a sensible way really.
>

Lost you here, define "thing"?


>
> >
> > I am also scared of moving pages, because of the Semantic Wiki cross
> reference issues that it may cause (we really need a bot for fixing all of
> the links after a move, especially since we have agreed upon a URL system),
> so the old URL system is still very much in place (dom/objects/bla,
> dom/methods/bla…).
>
> Julee and some others have been working on finalising the URL system I
> believe. Where did that get to? I'd say once the mess is sorted out, we
> will have something more solid and stable to work on.
>
> Apart form that, essentially it is just a matter of checking to make sure
> there is nothing already at the URL you are intending to move something to.
> I don't think it lets you just overwrite pages anyway.
>

I am not scared of overwriting (though that simply has not crossed my mind
;)), I am scared of broken references due to not removing the original URL.
I understand Semantic Wiki has some issues where the queries go crazy or
something, I do not remember. Some thread recently (a month or two)
mentioned it.


>
> >
> > One idea that I had in mind, is that the standards table should come
> from a list, with an option to either add to the list (like the current
> type system), or an option to add a custom one only to the page itself.
> > The problem (sort of) is that standards have lots of editions,
> especially working draft ones. So the links to them should be dynamic or
> flexible somehow, with a automatic completion to the current version.
> > (I admit I am sinning by always linking to the latest version, which can
> always change when it is a working draft (WHATWG HTML, W3C HTML5, DOM Level
> 3 Events, DOM Level 4, WHATWG DOM).)
>
> I'd say that when quoting specs, really we need to link to both the stable
> version of the spec, but then also the latest experimental version. So
> you'd have something like
>
> the <ul> element (Stable:HTML 4.01 | In progress:HTML5).
>
> With "Stable:HTML 4.01" pointing to
> http://www.w3.org/TR/html401/struct/lists.html
> and "In progress:HTML5" pointing to
> http://www.w3.org/TR/html5/the-ul-element.html#the-ul-element
>
> Of course, if the item being talked about is part of a working draft or
> other non-stable document, we would just need to link to the latest
> experimental version
>
> so something like
>
> getUserMedia (In progress:Media capture and Streams).
>
> linking to
> http://www.w3.org/TR/mediacapture-streams/#dom-navigator-getusermedia
>
>
> Would something like this work? I'd be happy to spec it out and write a
> guideline.
>

Yes and no, it can be broken if the latest version does not have it (for
example, PeerConnection turned into RTCPeerConnection. #dom-peer-connection
would lead to nowhere).
Unfortunately, the right thing to do would be to link to the exact version
where something is specified, but it breaks the fixed list idea.


> >
> >
> >
> > On Sat, Dec 1, 2012 at 12:32 PM, Chris Mills <cmills@opera.com> wrote:
> > Hi all,
> >
> > I was just thinking about this. I've seen some discussion going back and
> forth about adding documentation to WPD for stuff like Audio API and CSS
> regions. That's great, but surely we should concentrate more for a bit now
> on getting some of the existing HTML/CSS/JavaScript core stuff sorted out?
> Getting that core stuff in place is surely a higher priority than
> documenting nascent standards features that currently have limited browser
> support. I am happy to work with Julee and the others to formulate a plan
> for this.
> >
> > After I've got the high level page structures/IA/UX in a bit more
> working order over the next couple of weeks, I am happy to start
> contributing to the low level content myself.
> >
> > I'd say a general plan would be:
> >
> > * Split the content into areas of responsibility, e.g. CSS learning
> articles (concepts plus tutorials), CSS property references, CSS selector
> references, HTML learning articles, HTML element references, etc.
> > * Assign those areas to individuals who can take responsibility for
> their tending
> > * Get people working on those areas over the next couple of months. I'd
> say each domain area needs an editor and a proof reader, possibly a demo
> writer as well, as when Lea gets Dabblet in place, we'll need to install
> live demos on all the articles.
> >
> > Shall we discuss this at the general meeting on Monday?
> >
> > Chris Mills
> > Open standards evangelist and dev.opera.com editor, Opera Software
> > Co-chair, web education community group, W3C
> > Author of "Practical CSS3: Develop and Design" (
> http://my.opera.com/chrismills/blog/2012/07/12/practical-css3-my-book-is-finally-published
> )
> >
> > * Try Opera: http://www.opera.com
> > * Learn about the latest open standards technologies and techniques:
> http://dev.opera.com
> > * Contribute to web education: http://www.w3.org/community/webed/
> >
> >
> >
>
>