RE: Proposed Blog Post for MSDN JS Contribution

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 00:07:25 UTC