Proposed Blog Post for MSDN JS Contribution (was: JavaScript Reference from Microsoft)

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 Thursday, 18 April 2013 17:19:02 UTC