Re: Proposed Blog Post for MSDN JS Contribution

Hi, Eliot-

Great point. Any suggestions?

Regards-
-Doug

On 4/18/13 8:06 PM, Eliot Graff wrote:
> 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:13:52 UTC