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/document/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.readthedocs.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
_______________________________________________
Sync-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/sync-dev
