- From: Eliot Graff <Eliot.Graff@microsoft.com>
- Date: Fri, 19 Apr 2013 00:06:14 +0000
- To: Julee <julee@adobe.com>, Doug Schepers <schepers@w3.org>, "public-webplatform@w3.org" <public-webplatform@w3.org>
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