Re: Proposed Blog Post for MSDN JS Contribution

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.



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 [] Sent:
>> Thursday, April 18, 2013 4:56 PM To: Doug Schepers;
>> Subject: Re: Proposed Blog Post for MSDN JS
>> Contribution
>> +1 on this blog post and communications idea! Thanks, Doug. J
>> ---------------------------- @adobejulee
>> -----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?
>>> 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] [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 Friday, 19 April 2013 00:19:32 UTC