MDN/Projects/Completed/GitHub Integration: Difference between revisions

Jump to navigation Jump to search

MDN/Projects/Completed/GitHub Integration (view source)

Revision as of 23:25, 14 May 2013

2,473 bytes added ,  14 May 2013
no edit summary
No edit summary
Line 1: Line 1:
==What do we want?==
==What do we want?==


* To keep the documentation source for a product in GitHub, but the published docs on MDN.
This feature would enable product teams to maintain documentation in GitHub and publish it to MDN. So users of the docs would access them from MDN, but maintainers of the docs would add and edit them using GitHub. The versions of the docs on MDN would be read-only.
* To automate the publication of the docs to MDN when the source is changed.
 
* To publish the most recent build of the docs as well as the set of docs applicable to each formal release of the product.
Specifically, we'd want it to support the following things:
* To indicate to users which version of the docs is applicable to the most recent release of the product.
* keep the documentation source for a product in GitHub, but the published docs on MDN.
* To enable users to download a zip of a version of the docs, for use offline.
* automate the publication of the docs to MDN when the source is changed.
* publish the most recent build of the docs as well as the set of docs applicable to each formal release of the product.
* indicate to users which version of the docs is applicable to the most recent release of the product.
* enable users to download a zip of a version of the docs, for use offline.
 
==Why?==
 
* edit-review workflow: GitHub has very nice tool support for creating, reviewing, and revising content. Changes can be reviewed and corrected before going live, so you avoid those "This article is in need of a technical review." banners.
 
* editorial control: it's possible to control who gets to edit a page, and to make sure edits go through a particular channel. This means spam isn't a problem, and that it's possible to make sure doc updates are made consistently.
 
* writers don't need to use MDN's editor. The MDN editor is fine, but when I use it I find quite often that the WYSIWYG editor doesn't quite give me the control I want, and end up having to hand-write HTML, which is not a nice thing to have to do.
 
* the documentation is versioned alongside the code. This makes it simpler for versions of the documentation to track versions of the code. It's easier to say: this specific revision of the docs is applicable to this specific version of the product.
 
* it's relatively easy to generate documentation from the source. This might be full-on in-source documentation, or just something like reading metadata structures out of the docs (for example, the Add-on SDK docs read API stability and mobile support from the code that implements the APIs).


==How could we do it?==
==How could we do it?==
Line 85: Line 100:
== Readthedocs.org? ==
== Readthedocs.org? ==


We've talked in the past about using http://readthedocs.org/ to accomplish this. I'd love to do that, but it's unclear to me where in this proposal we're using readthedocs.org rather than just rolling our own thing.
Read the Docs is a [https://github.com/rtfd/readthedocs.org Open Source service] built on the [http://sphinx-doc.org/ Sphinx documentation platform]. It  supports docs written using [http://sphinx-doc.org/rest.html reStructuredText], and integrates with GitHub by way of [https://docs.readthedocs.org/en/latest/features.html#auto-updating post-receive webhooks].
 
In short, almost exactly the thing we need. And, it's already being put to  good use by a lot of projects at Mozilla. There are a few things that MDN would need to add, though:
 
# Support for formats other  than reStructuredText, so we can "be where the writers are" rather than expect everyone to use reST. Markdown is the most obvious target here.
# We need some glue code & theme work to integrate with MDN in general.
# Docs managed by this system should feed into the results of the in-house search feature we're developing right now.
# It might be interesting to make KumaScript as an available option to these docs
 
I think it's an open question whether we accomplish this by extending readthedocs.org or whether we roll our own thing. I'd much prefer us to use readthedocs.org, and to give any improvements back, but having looked a bit at readthedocs.org, it seems to be very heavily dependent on the docs using Sphinx/reStructuredText - so if it's important to us to support other formats (which it probably is) and other ways of generating a docset from a pile of source files, then it might be a big change.


I can understand how we could do our own thing. And on the other side, I can understand how we could use readthedocs.org more or less as-is. But having looked a bit at readthedocs.org, it seems to be very heavily dependent on the docs using Sphinx/reStructuredText - so if it's important to us to support other formats (which it probably is) and other ways of generating a docset from a pile of source files, then it might be a big change.
===References===
https://etherpad.mozilla.org/github-mdn
Wbamberg
canmove, Confirmed users
737

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/656019"

Navigation menu