Documentation----temporary-notes-for-the-move-to-readthedocs.md

-To make maintenance and contributions easier, we're considering taking the docs out of the main repo and encourage contributions better.
+To make maintenance and contributions easier, we're taking the docs out of the main repo.
 
-Current test: mathjax-docs.readthedocs.org or github.com/pkra/mathjax-docs
+Current test: 
+* [MathJax Docs repo](http://mathjax-docs.readthedocs.org) -- github.com/pkra/mathjax-docs
+* [Experimental docs](http://mathjax-docs-experimental.readthedocs.org)
 
-Readthedocs is a service that automatically builds Sphinx documentation (as HTML, pdf and epub). Github offers a webhook so that readthedocs builds the documentation whenever a change occurs in the repository. (Note: We don't have to separate the docs to use readthedocs, it can find the docs in the main repo.)
+[Readthedocs](http://readthedocs.org) is a service that automatically builds Sphinx documentation (as HTML, pdf and epub). 
 
-Readthedocs has a nice standard theme that offers better features than ours (including version).
+Github offers a webhook so that readthedocs builds the documentation whenever a change occurs in the repository. (Note: We don't have to separate the docs to use readthedocs, it can find the docs in the main repo. But we decided that it makes sense to separate them)
 
 The idea is to host the docs at docs.mathjax.org. Accordingly, we need to offer users a clear way back to www.mathjax.org
 
+Readthedocs has a nice standard theme that offers better features than ours (including version). However, the theme does not allow enough customization (e.g. breadcrumbs to www.mathjax.org). Since we will switch the main website  to a twitter-bootstrap look, Peter looked into bootstrap-based sphinx themes.
+ 
 Since we host the docs on github, there's the additional advantage of editing the files in githubs webinterface (wich creates a fork and pull request).
 
-Thanks to the support on the readthedocs issue tracker (https://github.com/rtfd/readthedocs.org/issues/226), we can make use of this and add a "edit on github" link to each documentation page. We still need a "version warning" (see https://github.com/rtfd/readthedocs.org/issues/220). But we're probably loosing the SEO on the docs when switching to docs.mathjax.org which might reduce the problem...
+Thanks to the support on the readthedocs issue tracker (https://github.com/rtfd/readthedocs.org/issues/226), we can add a "edit on github" link to each documentation page. We also have a "version warning". 
+
+But we're probably loosing the SEO on the docs when switching to docs.mathjax.org which might reduce the problem...
+
+The bad thing: the url for these "edit on github" links has to be (partially) hard coded in `_templates` -- for each version of the docs (see also the issue 226 there). 
+
+Since the sphinx-bootstrap theme has to be customized anyway, this isn't as big a problem as it would be with the main theme. Also, sphinx-bootstrap has a lot of nice features and is being maintained more actively.
 
-The bad thing: the url for these "edit on github" links has to be (partially) hard coded in `_templates` -- for each version of the docs (see also the issue 226 there). It's a small price to pay right now, but if we get to localization of our docs we might want to revisit this.
+Using [advice from stackoverflow](http://stackoverflow.com/questions/359424/detach-subdirectory-into-separate-git-repository), we will keep the entire editing history in the new repository.
 
---------
 
-New attempt using http://stackoverflow.com/questions/359424/detach-subdirectory-into-separate-git-repository to keep the entire editing history in the new repository. It might be a little silly (since the history remains in the main repo), but since we can, we should.
+TODO:
 
+* add readme and license to the mathjax-docs repo & push to MathJax/mathjax-docs
+* switch themes on mathjax-docs to the sphinx-bootstrap theme with Peter's modification (Peter should fork the sphinx-bootstrap theme and make the modifications there)
+* redirect the old docs to the new docs, i.e., `mathjax.org/docs` to `docs.mathjax.org/en/`
\ No newline at end of file