Re: Proposed Blog Post for MSDN JS Contribution

+1 on this blog post and communications idea! Thanks, Doug. J


-----Original Message-----
From: Doug Schepers <>
Date: Thursday, April 18, 2013 10:23 AM
To: "" <>
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?
>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]
>> [2]
>> 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 Thursday, 18 April 2013 23:56:41 UTC