- From: Doug Schepers <schepers@w3.org>
- Date: Thu, 18 Apr 2013 13:23:09 -0400
- To: "public-webplatform@w3.org" <public-webplatform@w3.org>
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 Thursday, 18 April 2013 17:23:17 UTC