<div dir="ltr"><div><div>Thanks Mark for the great comparison. This is a great discussion to have.<br><br></div>I recognize that I am not the primary customer of this content so I will ultimately support whatever you guys pick since it is meant to help developers working on Sync. <br>But.. if I had to pick my preference would be for MDN for the exact reasons you identified. <br>Who knows, maybe contributors will help migrate external content to MDN once we start to use it as an index. (prob wishful thinking though)<br><br></div></div><div class="gmail_extra"><br clear="all"><div><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><div></div><div>--<br>Alex Davis <span>// Mountain View</span></div><div>Product Manager // FxA & Sync<br></div>(415) 769-9247</div><span></span></div><div>IRC & Slack: adavis<br></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div>
<br><div class="gmail_quote">On Thu, Mar 30, 2017 at 12:24 AM, Mark Hammond <span dir="ltr"><<a href="mailto:mhammond@mozilla.com" target="_blank">mhammond@mozilla.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 3/14/17 7:39 PM, Mark Hammond wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
The desktop Sync team has an OKR this quarter to decide how to "fix" the Sync documentation - it's not that it's "broken", it's more that, in general, it doesn't exist (or if it does, it's spread out in various locations)<br>
<br>
I've created a google doc where I'm fleshing out both the status quo and a strategy for the future - <a href="https://docs.google.com/document/d/1gkOUnO8FrNH3mtWggByT4axtrNpgNFw2l8l6B2uEUk4/edit?usp=sharing" rel="noreferrer" target="_blank">https://docs.google.com/docume<wbr>nt/d/1gkOUnO8FrNH3mtWggByT4axt<wbr>rNpgNFw2l8l6B2uEUk4/edit?usp=s<wbr>haring</a> <br>
</blockquote>
<br></span>
Thanks for all the comments in that document. IMO there are 2 clear alternatives for our future documentation needs:<br>
<br>
* readthedocs - for example, <a href="https://mozilla-services.readthedocs.io/en/latest/" rel="noreferrer" target="_blank">https://mozilla-services.readt<wbr>hedocs.io/en/latest/</a><br>
<br>
The workflow here is that we'd create a new github repo where people can commit documentation as reStructured text documents, and the docs would be automatically generated.<br>
<br>
The primary downside I see here is the additional tooling required to ensure that what is being committed looks OK - while there are tools for this, including tools for popular editors, I believe it's still going to be a pain, and in practice, only accessible to developers already comfortable with version control and advanced editors.<br>
<br>
* MDN - eg, <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/TPS" rel="noreferrer" target="_blank">https://developer.mozilla.org/<wbr>en-US/docs/Mozilla/Projects/TP<wbr>S</a><br>
<br>
The workflow here is that it's a wiki - edit and preview in place.<br>
<br>
While I was dismissive of Wikis in the document, it's probably reasonable to consider MDN a somewhat special case - it's a well maintained and implemented wiki that is of strategic interest to Mozilla given how many important documents it holds.<br>
<br>
The key limitation I see here is that while there's some level of history available for pages, it's not as good as (say) Mercurial or git, and doesn't really offer a "review" flow like a github repo offers.<br>
<br>
On the flip side, a key benefit is that it's easy to contribute to - eg, people who aren't particularly comfortable with Mercurial are still able to contribute.<br>
<br>
All things considered, I'm somewhat torn between the 2, but have a slight preference towards MDN for the reasons above.<br>
<br>
How do others feel about declaring that, say, <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Sync" rel="noreferrer" target="_blank">https://developer.mozilla.org/<wbr>en-US/docs/Mozilla/Projects/Sy<wbr>nc</a> becomes the official "home" for all sync documentation, and in the short term we use this as an index to externally hosted documentation, in the medium term we create all new Sync documentation inside MDN, and over the longer term we move existing documentation here?<div class="HOEnZb"><div class="h5"><br>
<br>
Mark<br>
______________________________<wbr>_________________<br>
Dev-fxacct mailing list<br>
<a href="mailto:Dev-fxacct@mozilla.org" target="_blank">Dev-fxacct@mozilla.org</a><br>
<a href="https://mail.mozilla.org/listinfo/dev-fxacct" rel="noreferrer" target="_blank">https://mail.mozilla.org/listi<wbr>nfo/dev-fxacct</a><br>
</div></div></blockquote></div><br></div>