Thanks Mark for the great comparison. This is a great discussion to have. 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. But.. if I had to pick my preference would be for MDN for the exact reasons you identified. Who knows, maybe contributors will help migrate external content to MDN once we start to use it as an index. (prob wishful thinking though)
-- Alex Davis // Mountain View Product Manager // FxA & Sync (415) 769-9247 IRC & Slack: adavis On Thu, Mar 30, 2017 at 12:24 AM, Mark Hammond <[email protected]> wrote: > On 3/14/17 7:39 PM, Mark Hammond wrote: > >> 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) >> >> I've created a google doc where I'm fleshing out both the status quo and >> a strategy for the future - https://docs.google.com/docume >> nt/d/1gkOUnO8FrNH3mtWggByT4axtrNpgNFw2l8l6B2uEUk4/edit?usp=sharing >> > > Thanks for all the comments in that document. IMO there are 2 clear > alternatives for our future documentation needs: > > * readthedocs - for example, https://mozilla-services.readt > hedocs.io/en/latest/ > > 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. > > 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. > > * MDN - eg, https://developer.mozilla.org/en-US/docs/Mozilla/Projects/TPS > > The workflow here is that it's a wiki - edit and preview in place. > > 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. > > 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. > > 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. > > All things considered, I'm somewhat torn between the 2, but have a slight > preference towards MDN for the reasons above. > > How do others feel about declaring that, say, > https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Sync 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? > > > Mark > _______________________________________________ > Dev-fxacct mailing list > [email protected] > https://mail.mozilla.org/listinfo/dev-fxacct >
_______________________________________________ Dev-fxacct mailing list [email protected] https://mail.mozilla.org/listinfo/dev-fxacct
