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?


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]
> [2]
> 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