W3C home > Mailing lists > Public > public-webplatform@w3.org > November 2013

Re: Second JS bulk upload

From: Doug Schepers <schepers@w3.org>
Date: Sun, 24 Nov 2013 18:07:33 -0500
Message-ID: <529286B5.8000408@w3.org>
To: Max Polk <maxpolk@gmail.com>
CC: Webplatform List <public-webplatform@w3.org>
Hi, Max–

First off: fantastic work, thank you!

Regarding hierarchies vs flat structure, we've already made an 
architecture decision to have a hierarchy of pages, with topics (HTML) 
subdivided into subtopics (properties, selectors, media queries, etc.). 
We're going to do the same with JavaScript.

In addition to avoiding conflicts (e.g. to disambiguate the 'border' 
attribute of the HTML <table> element from the CSS 'border' property), 
it also presents a nice mental model of the Open Web Platform, and 
intuitive navigation within a topic.

Of course, we can't always have a single definitive, all-encompassing 
tree structure, since many things are connected in multiple ways. This 
is where categories are also useful, as you say, and we do need to look 
at how to deal with them more systematically.

So, I agree with Phistuck that we shouldn't flatten the structure out 
too much, though we can talk about optimizations.

Regards-
-Doug

On 11/24/13 3:48 PM, Max Polk wrote:
> In a dictionary or encyclopedia, everything is at the same top-level
> namespace.  In a wiki, in some rare cases subpages can be useful, but to
> categorize in Mediawiki, the main approach is to "tag" the page with a
> Category:Something inside double square brackets.  You can add multiple
> categories.
>
> To diverge from the built-in power of Mediawiki categorization by trying
> to replace it with subpages is a mistake.  Just click "random page" over
> and over again on Wikipedia and see how many subpages you run into
> (almost never).
>
> We already have several top-level subdivisions of webplatform docs, one
> of them being the /javascript/ page path.  Let's not use additional
> paths when all we need to do is "tag" pages (with a category).  There is
> even a facility to list all pages in a category automatically, and you
> can even edit that page.  For example, see this:
>
> http://en.wikipedia.org/wiki/Category:Algebra
>
> It is a category page, with autogenerated page inclusion.  Just "tag" a
> page with "[[Category:Algebra]]" and it appears in the category page.
> But you can also introduce the category by editing the category page
> itself (the material on the top).
>
> Trying to use subpaths under /javascript/ in this wiki feels to me like
> a lack of harmony, awkward, and a divergence from the best strengths
> Mediawiki has to offer, especially since the power of "tagging" pages
> (categorization) has been completely missing, from all our conversations.
>
> Best approach is to try to tag (categorize) pages first, then, and only
> then if that fails, fall back to additional subpage paths.  P.S. it
> won't fail.  ;-)
>
>
>
> On Sun, Nov 24, 2013 at 2:23 AM, PhistucK <phistuck@gmail.com
> <mailto:phistuck@gmail.com>> wrote:
>
>     It seems a bit messy, to have the API and the language reference
>     (syntax, statements, operators) in the same level...
>     For example -
>     javascript/String
>     javascript/Statements
>
>     Also, if we keep them (and I think we should), any non API path
>     component ("Statements", "Operators") should be lower case.
>
>
>     ☆*PhistucK*
>
>
>     On Sun, Nov 24, 2013 at 6:01 AM, Max Polk <maxpolk@gmail.com
>     <mailto:maxpolk@gmail.com>> wrote:
>
>         The next round of JavaScript pages have just been uploaded.
>           Root path:
>
>         http://docs.webplatform.org/__test/javascript
>         <http://docs.webplatform.org/test/javascript>
>
>         The links now work, it should be navigable at this point.  Note
>         that this page, in the original, was intended to the landing
>         page, which pointed to the below top-level pages:
>
>         http://docs.webplatform.org/__test/javascript/JavaScript___Reference
>         <http://docs.webplatform.org/test/javascript/JavaScript_Reference>
>
>         Then these top-level pages, in the original, were helpers to
>         point you to the other pages:
>
>         http://docs.webplatform.org/__test/javascript/Functions
>         <http://docs.webplatform.org/test/javascript/Functions>
>         http://docs.webplatform.org/__test/javascript/Statements
>         <http://docs.webplatform.org/test/javascript/Statements>
>         http://docs.webplatform.org/__test/javascript/Operators
>         <http://docs.webplatform.org/test/javascript/Operators>
>         http://docs.webplatform.org/__test/javascript/Objects
>         <http://docs.webplatform.org/test/javascript/Objects>
>         http://docs.webplatform.org/__test/javascript/Properties
>         <http://docs.webplatform.org/test/javascript/Properties>
>
>         Why are those there?
>
>         Because we took original html files that were arranged very
>         tree-like in their URL path structure, and began *flattening* to
>         be more like what an encyclopedic venue such as a wiki is good
>         at storing and finding.  By flattening I mean taking out the
>         "Objects/" path prefix to many pages, and things like that.
>           While we still use subpages, we don't technically need that
>         landing page or the subtopic pages just so everything can be
>         found.  A wiki you simply search for things.  Having said that
>         these pages still look useful to me, although they will probably
>         be reworked.
>
>         We are messaging the pages to be more like a wiki where URLs are
>         very important, and less like a tech site whose URLs don't
>         always have to make sense.  We want the URLs to be clean.
>           Fortunately for us, they were already very clean and well
>         organized to begin with.  That definitely is making our
>         flattening effort a lot easier.  Three cheers to organization
>         the pages donator Microsoft imposed, and the good content!
>
>         The work below is still outstanding:
>
>             Automation to do:
>             2. talk about static method page name (X/X.method versus
>             X/method)
>             3. talk about Global/* (nobody says
>             "Global.decodeURIComponent" so maybe hide the Global prefix)
>
>             Non-automation to do:
>             1. Discuss keeping Object/constructor and erase six other
>             pages (Array/constructor, Boolean/constructor, etc), that
>             are essentially duplicates.
>             2. Discuss keeping Object/prototype and erase six other
>             pages (Array/prototype, Boolean/prototype, etc), likewise.
>             3. Probably should not erase six other pages for valueOf:
>             (Array/valueOf , Boolean/valueOf , etc), likewise, since
>             they are each custom versions that return different things
>             (a string, an array, a boolean value, etc).
>             4. Create String/X pages for each of the String HTML Tag
>             Methods (string.anchor, string.big, string.blink, etc)
>             5. Discuss folding arguments/0 n Properties and RegExp/1 9
>             Propertiesinto their main page then delete them
>
>
>
>
>
Received on Sunday, 24 November 2013 23:07:42 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:13:56 UTC