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

Re: Proposed Blog Post for MSDN JS Contribution

From: Patrick D'Souza <patrick.dsouza@gmail.com>
Date: Thu, 18 Apr 2013 20:24:42 -0400
Message-Id: <DEF0C7C1-26CD-4097-8297-FC61A0738BF5@gmail.com>
Cc: Eliot Graff <Eliot.Graff@microsoft.com>, Julee <julee@adobe.com>, "public-webplatform@w3.org" <public-webplatform@w3.org>, Alex Komoroske <komoroske@google.com>
To: Doug Schepers <schepers@w3.org>
We can look at piwik and look at data for the best day and time. I'm on my way home. I can look into piwik when I'm on my laptop.


On Apr 18, 2013, at 8:19 PM, Doug Schepers <schepers@w3.org> wrote:

> Hey, folks-
> Thinking of timing... should we post this on Monday instead of Friday? When are we likely to get the best result?
> Also, do we want to identify specific individuals who will drive it? It might look good if we had one Microsoft person (so it doesn't seem like a "dump-and-run") and a person from some other company (to give it more neutrality)... Alex, from the templates side, you might be a good candidate.
> [1] https://twitter.com/nsteinmetz/status/324748962080886784
> Regards-
> -Doug
> On 4/18/13 8:13 PM, Doug Schepers wrote:
>> Hi, Eliot-
>> Great point. Any suggestions?
>> Regards-
>> -Doug
>> On 4/18/13 8:06 PM, Eliot Graff wrote:
>>> Thank you, Doug.
>>> I like this a lot. I think we could show a little more emphatically
>>> somewhere that we have people who will act in leadership roles in the
>>> migration but that should leaders arise, they're welcome, too. As it
>>> reads now, it's a little daunting. Who's organizing the migration?
>>> What am I getting into? If I want to really drive this area, can I?
>>> Those seem to be unanswered questions.
>>> Eliot
>>> -----Original Message----- From: Julee [mailto:julee@adobe.com] Sent:
>>> Thursday, April 18, 2013 4:56 PM To: Doug Schepers;
>>> public-webplatform@w3.org Subject: Re: Proposed Blog Post for MSDN JS
>>> Contribution
>>> +1 on this blog post and communications idea! Thanks, Doug. J
>>> ---------------------------- julee@adobe.com @adobejulee
>>> -----Original Message----- From: Doug Schepers <schepers@w3.org>
>>> Date: Thursday, April 18, 2013 10:23 AM To:
>>> "public-webplatform@w3.org" <public-webplatform@w3.org> Subject: Re:
>>> Proposed Blog Post for MSDN JS Contribution
>>>> Hi, folks-
>>>> One more thought occurred to me.
>>>> Maybe we can get some well-known JavaScript luminaries to help
>>>> with this integration, retweet it, review it, endorse it, and
>>>> write complementary materials (tutorials, and so on) to amplify the
>>>> message here?
>>>> Regards- -Doug
>>>> On 4/18/13 1:18 PM, Doug Schepers wrote:
>>>>> Hi, folks-
>>>>> Our original tweet [1] came late in the (East Coast) day
>>>>> yesterday; it's gotten 117 retweets, but I think we can do
>>>>> better.
>>>>> Rather than just retweet it again from @w3c during EU hours, I
>>>>> thought it would be better to write up a blog post with a more
>>>>> detailed call to action, and tweet that, then get partners to
>>>>> retweet a bit earlier in the day.
>>>>> So, I took a first stab at a blog post [2] (text below, without
>>>>> links).
>>>>> Constructive criticism welcome, as are suggestions on the body of
>>>>> the corresponding tweet. I propose to post the final version of
>>>>> this tomorrow morning ET (afternoon UTC).
>>>>> [1] https://twitter.com/webplatform/status/324645876536598529 [2]
>>>>> http://blog.webplatform.org/?p=335&preview=true
>>>>> Regards- -Doug
>>>>> [[ JavaScript Docs from MSDN Apr 18 2013 by Shepazu
>>>>> A Web documentation site without JavaScript is like a browser
>>>>> without JavaScript.
>>>>> The JavaScript topic on Web Platform Docs is sparse, especially
>>>>> our reference articles. That¹s why we were so thrilled when
>>>>> Microsoft offered us their excellent JavaScript documentation
>>>>> from MSDN.
>>>>> We briefly discussed how we should integrate it into Web
>>>>> Platform Docs, and quickly decided that it would be most
>>>>> appropriate for Microsoft to simply donate the HTML documents,
>>>>> and we would let the community have ownership over the
>>>>> integration. After all, this is a community-based site, and we
>>>>> want the community to be involved in decisions major and minor.
>>>>> So, this is where you come in!
>>>>> What can you do?
>>>>> Integration is not a trivial task. It¹s not difficult, either,
>>>>> but there are lots of moving parts.
>>>>> First, we have to settle what on the URL structure. How do we
>>>>> want to organize the different pages within our information
>>>>> hierarchy, so that it¹s consistent, easy to find and reference,
>>>>> and avoids naming clashes?
>>>>> Second, we have to make MediaWiki templates. We need to define
>>>>> how each page type (object, property, method, etc.) is
>>>>> structured, again for consistency and to make it easy for an API
>>>>> to extract just the information needed.
>>>>> Third, we have to come up with a methodology to convert the HTML
>>>>> content into the wiki. Converting 400+ pages by hand would be
>>>>> tedious, but an automated import script is likely to be
>>>>> error-prone, even with consistent and well-structured HTML like
>>>>> the export from MSDN. Which sections do we use? What do we do if
>>>>> we need to add structure that doesn¹t exist in the original? How
>>>>> shall we review all the converted documents? Should we import
>>>>> first into our test wiki instance, then transfer into the main
>>>>> wiki? In some cases, there may be duplicates of content already
>>>>> in the wiki; how shall we resolve that? What import script should
>>>>> we use (and can we revise and reuse the script from our original
>>>>> MSDN mass-import back in October)?
>>>>> You can help us answer these questions, and ask questions we
>>>>> didn¹t think about. And you can volunteer to help do the
>>>>> conversion, review, or other parts of the project. To help manage
>>>>> this process, we created a special sub-project, MSDN-JS, in our
>>>>> issue tracker/project management tool. Create a WPD account,
>>>>> subscribe to our public-webplatform mailing list and introduce
>>>>> yourself, and we¹ll help get you started. What have we already
>>>>> done?
>>>>> A couple of days ago, Microsoft¹s Kathy Shoesmith and her team
>>>>> exported the whole JavaScript branch of their MSDN content from
>>>>> their CMS as well-structured HTML; they also provided some
>>>>> support files, including a hierarchy index in XML, and an Excel
>>>>> file with the correspondence table between file names (e.g.
>>>>> ³1b512146-1e8a-44a4-89da-6cc5338d15cb.htm² shudder) and article
>>>>> title (e.g., ³getMilliseconds Method (Date) (JavaScript)²).
>>>>> I converted that spreadsheet file to a JSON object, and used
>>>>> node.js to rename all the files (e.g.
>>>>> ³getMilliseconds-Method__Date.html²) and convert the XML
>>>>> hierarchy index to an HTML nested list to serve as a table of
>>>>> contents, then pushed everything to WebPlatform¹s Github msdn-js
>>>>> repo.
>>>>> So, there¹s where we are. Where we go next is up to you. Why not
>>>>> use MDN¹s JavaScript docs?
>>>>> MDN, the Mozilla Developer Network, already excellent JavaScript
>>>>> documentationŠ as well they should! Mozilla¹s Brendan Eich
>>>>> invented JavaScript, and Mozilla continues to drive and improve
>>>>> JavaScript in their browser and in Ecma standardization.
>>>>> Moreover, they¹ve had 8 years of expert JavaScript developer
>>>>> contributions to MDN, so it¹s rock-solid. And Mozilla is one of
>>>>> the Web Platform stewards. Why not just reuse their JavaScript
>>>>> content?
>>>>> As Mozilla¹s Janet Swisher explains, that content was contributed
>>>>> to MDN under the CC-BY-SA (Creative Commons Attribution
>>>>> Share-Alike) license, rather than the more permissive and
>>>>> reusable CC-BY license that WPD offers, so for the long-term goal
>>>>> of making and keeping WPD as open as possible, we needed another
>>>>> solution. Microsoft donating their content is an ideal starting
>>>>> point for comprehensive community-driven documentation.
>>>>> And JavaScript is still evolving (rapidly!), so WPD community
>>>>> engagement by JavaScript experts will help us evolve our content
>>>>> along with it. You want to future-proof our documentation by
>>>>> adding a tutorial and examples on JavaScript Futures? Go for it!
>>>>> We need you!
>>>>> Even with big content contributions like this one from
>>>>> Microsoft, this site will never succeed in our mission without
>>>>> consistent contributions and engagement from our community. So,
>>>>> consider your effort in integrating these documents a ³matching
>>>>> donation² and help us make WPD the documentation site we all
>>>>> need. ]]
Received on Friday, 19 April 2013 08:00:15 UTC

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