<html><head><style>body{font-family:Helvetica,Arial;font-size:13px}</style></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div id="bloop_customfont" style="font-family:Helvetica,Arial;font-size:13px; color: rgba(0,0,0,1.0); margin: 0px; line-height: auto;"><span style="color: rgb(160, 160, 168);">On December 16, 2013 at 1:21:06 PM, Gregory Szorc (</span><a href="mailto://gps@mozilla.com">gps@mozilla.com</a><span style="color: rgb(160, 160, 168);">) wrote:</span></div> <div><blockquote type="cite" class="clean_bq" style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);"><span><div><span style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;">I agree our current mechanism for JS documentation is pretty bad. We<span class="Apple-converted-space"> </span></span><br style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><span style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;">desire to document both the source and MDN for obvious reasons. But<span class="Apple-converted-space"> </span></span><br style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><span style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;">nobody wants to burdened with writing docs twice. So typically in-tree<span class="Apple-converted-space"> </span></span><br style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><span style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;">or MDN docs suffer. Neither is great for maintainability or consumers.<span class="Apple-converted-space"> </span></span><br style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><span style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;">IMO we should just write in-tree source docs and export to MDN. Goodbye<span class="Apple-converted-space"> </span></span><br style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><span style="color: rgb(0, 0, 0); font-family: helvetica; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;">syncing problem.<span class="Apple-converted-space"> </span></span></div></span></blockquote></div><p>We have plans to add support to MDN for allowing content to be "pushed" onto MDN from other sites using scripts or the like. There is already the beginnings of a "write" API that allows content to be injected into MDN, and with that in concert with permissions management, it would be possible to set up the JSAPI section of MDN such that it was pushed onto the wiki by a tool that interpreted in-source comments and output HTML formatted for the wiki.</p><p>This could be a "best of both worlds" scenario that you guys could be quite happy with.</p><p>The only reason we haven't finished implementing support for this is that no teams have stepped up to say they'd definitely use it; once one does, I think it wouldn't take all that terribly long to complete, since much of the underlying functionality is partly or even mostly implemented.</p><div id="bloop_sign_1387226284547982080" class="bloop_sign"><div style="font-family: helvetica, arial;">-- <br>Eric Shepherd<br>Developer Documentation Lead</div><div style="font-family: helvetica, arial;">Mozilla</div><div style="font-family: helvetica, arial;">Blog: http://www.bitstampede.com/</div><div style="font-family: helvetica, arial;">Twitter: http://twitter.com/sheppy</div></div></body></html>