Fwd: Re: JS Information Architecture for WebPlatform.org

Hi, folks–

Here's some feedback we got from Rick Byers from Google on the 
JavaScript project.

Regards–
–Doug


-------- Original Message --------
Subject:  Re: JS Information Architecture for WebPlatform.org
Date:  Mon, 12 Aug 2013 23:19:08 -0400
From:  Rick Byers <rbyers@google.com>
To:  Doug Schepers <schepers@w3.org>



Hey Doug, see inline

On Fri, Aug 9, 2013 at 12:00 PM, Doug Schepers <schepers@w3.org
<mailto:schepers@w3.org>> wrote:

     Hi, Rick–

     I hope you're doing well.

     You're one of a small number of people I'm contacting to help us
     with some guidance on how we should structure our JavaScript docs at
     WebPlatform.org [1]. I'd really appreciate your insight, if you have
     the time (which should only be a few minute for a first-pass glance,
     more if you're really into it).


     We are importing a bunch of reference articles documents on JS from
     MSDN, which is actually a pretty good starting point; obviously, we
     wil want to flesh them out more, but we want to get this initial
     import right.

     We want the docs to be structured in a way that's useful and
     intuitive for developers, but also technically correct from a
     language-design point of view. This is reflected in 3 things:

     1) URL hierarchy
     2) Page structure
     3) Categorization (tags)

     Would you mind taking a look at what we have so far for these, as a
     sanity check? The big one right now is URL hierarchy; if you have
     time to look at the other items, that would be gravy.


Sure, I took a quick look now.  At a high level my guidance would be
when in doubt, look to MDN
(https://developer.mozilla.org/en-US/docs/Web/JavaScript/) for guidance.
   I've found MDN to be the most useful resource and have never had any
complaints with it's structure, etc.  Of course in practice the quality
of the content is probably more important and a harder problem to solve
than the quality of the organization and structure.

Are you guys working with the Mozilla folks on webplatform.org
<http://webplatform.org> at all?  MDN seems so close to what you're
trying to achieve, it would be a shame if efforts couldn't be combined
somehow.  I know Google folks approached them on a docs collaboration at
some point, but it apparently fell apart - I don't know the details.

     ==URL hierarchy==

     We have a write-up of the current thinking for the URL structure
     [1][2]. On the table on github, "Page name" contains the relative
     URL for each article; for example "Objects/Array/length Property"
     would be an article named "length Property" at the URL:
     http://docs.webplatform.org/__wiki/javascript/Objects/Array/__length
     <http://docs.webplatform.org/wiki/javascript/Objects/Array/length>
     Property

     (Note that MediaWiki is case-sensitive for URLs; we're moving to a
     system that's not.)


This seems totally reasonable to me.  I have a slight preference for
omitting the suffixes ('Property' etc.) - I _think_ they'll almost
always be obvious from the context.

Is there a separate effort to document the DOM APIs?  I suspect most web
developers don't differentiate between built-in Objects and those
provided by the DOM.  As long as there is an easy way to search (eg.
"Element" or "Array") it's probably fine.

     ==Page structure==

     We're more or less structuring each page like they have on MSDN [4],
     but if you have the gumption to suggest how to optimize this for
     developer consumption, we're all ears.


Are you planning on having any sort of 'browser compatibility' table?
   Eg.  Note the difference between the MSDN and MDN entries for Map.
   For the typical web developers (who is trying to reason about all
browsers at once) I think the MDN structure is more useful.
http://msdn.microsoft.com/en-us/library/ie/dn263029(v=vs.94).aspx
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map

Another thing I like better about MDN then MSDN is links to the
authoritative source (specs, etc.).  MSDN is written to be self
contained (I talked to docs writers about this when I was at Microsoft)
and so they tend to err on the side of omitting information rather than
linking to outside sources for more details.  MDN on the other hand does
a great job of providing an overview with links to the specs when you
want to drill further.  Again see the Map example.

     ==Categorization==

     In addition to the exlicit URL structure, which clusters like things
     together (date stuff, array stuff), there might be other useful
     collections or categorizations of some or all of these things
     (beyond the obvious "javascript" tag). We haven't thought too deeply
     about this aspect, but if there are obvious implicit tag clusters
     that you think would help navigation and exploration, we'd be
     interested to hear about them.


As you might imagine given my employer, I think manual categorization of
large data sets is generally low value for the cost.  Search is the
primary way users will find things (eg. I can google 'MDN foo' and get
the MDN docs I'm looking for as one of the top hits every single time).
   Perhaps there's a role for higher level conceptual documentation that
links to related pages (eg. a page describing trade-offs of different
types of collections), but perhaps that's better served elsewhere in the
community with webplatform.org <http://webplatform.org> focusing on
being the canonical reference for details.

Hope this helps!
    Rick


     [1] http://docs.webplatform.org/__wiki/javascript
     <http://docs.webplatform.org/wiki/javascript>
     [2] http://docs.webplatform.org/__wiki/WPD:Projects/javascript
     <http://docs.webplatform.org/wiki/WPD:Projects/javascript>
     [3]
 
https://github.com/maxpolk/__msdn-js-conversion/blob/__master/round-alice/upload-__mapping.wiki
 
<https://github.com/maxpolk/msdn-js-conversion/blob/master/round-alice/upload-mapping.wiki>
     [4]
 
http://msdn.microsoft.com/en-__us/library/ie/yek4tbz0(v=vs.__94).aspx 
<http://msdn.microsoft.com/en-us/library/ie/yek4tbz0(v=vs.94).aspx>

     Thanks!
     -Doug

Received on Sunday, 3 November 2013 22:09:30 UTC