Re: Proposed Blog Post for MSDN JS Contribution

Hi, folks-

Here's a second pass... I'm not particularly happy with it, so I'd 
welcome a rewrite. In particular, I'm not sure I struck the right 
balance of brevity and "naming names", or was quite reassuring enough. 
And it may be asking a bit too stridently for help...


=New JavaScript Docs from MSDN!=
Apr 18 2013 by Shepazu

A Web documentation site without JavaScript is like a browser without 

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.

If you’re feeling intimidated by all those open questions… don’t worry! 
We’ve already got a skilled community, like Alex Komoroske (Google) who 
authored most of the site templates, Eliot Graff (Microsoft) who helped 
design WPD’s information architecture, and content drivers like Chris 
Mills (Opera and W3C), Julee Burkekin (Adobe), and Scott Rowe (Google), 
as well as many other folks who can lead the integration… or step aside 
to let new leaders take the initiative!

==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) 

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 has great JavaScript 
documentation, 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 03:27:00 UTC