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

← Older edit

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

Revision as of 20:13, 18 December 2014

3,760 bytes added , 18 December 2014

m

Aspivak moved page MDN/Projects/Development/GitHub Integration to MDN/Projects/Completed/GitHub Integration

Aspivak

canmove, Confirmed users

842

edits

@@ Line 13: / Line 13: @@
 * 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).
-* 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.
+== How will we measure the value? ==
-* 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.
+What is the expected value and impact and how will we measure it?
-* 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).
+* Increase MDN reach?
+** More docs on MDN?
+** New audience coming to MDN?
+* Improve documentation quality?
+** Readers bounce around less?
+* What else?
 ==How could we do it?==
@@ Line 98: / Line 105: @@
 For the second interface, the code could be taken from the repo itself. For the first, it can't, unless the generic service is happy to clone the repo on every commit (which might be OK, depending on how large and active the repo is).
-== Readthedocs.org? ==
+== Docs as a Service ==
+We could implement Docs-as-a-Service from MDN. There are a number of existing projects and platforms that we could re-use roughly as follows:
+# Create an MDN theme/layout for the platform
+# Stand up our own server process for the platform
+## Generates docs
+## Publishes them under MDN
+## Indexes them to our search index
+# Expose our server process as a [https://help.github.com/articles/post-receive-hooks GitHub post-receive hook]
+When the platform is set up, GitHub projects can add MDN as a post-receive hook.
+=== Readthedocs.org ===
 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].
@@ Line 108: / Line 127: @@
 # 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.
-===References===
+=== Jekyll ===
+[http://jekyllrb.com/docs/home/ Jekyll] is another static site generator that can take a template directory of Markdown (or Textile) and Liquid converters to create static websites. It's the engine behind GitHub Pages.
+=== Docco ===
+[http://jashkenas.github.io/docco/ Docco] generates documentation from [https://en.wikipedia.org/wiki/Literate_programming "Literate Code"] and is starting to catch on in the JavaScript community:
+* [http://backbonejs.org/docs/backbone.html backbone.js]
+* [http://underscorejs.org/docs/underscore.html underscore.js]
+* [http://pivotal.github.io/jasmine/ Jasmine]
+* [http://darobin.github.io/test-harness-tutorial/docs/using-testharness.html W3C testharness.js]
+== Potential test subject: the Emscripten Wiki ==
+Emscripten, Mozilla's LLVM bytecode -> JavaScript compiler, currently has its most complete source of documentation on the Emscripten Wiki located at https://github.com/kripken/emscripten/wiki. This project already has a dedicated community of contributors, although the site currently doesn't look very professional and could do with some editing and structural improvements.
+The MDN team and Emscripten engineers would like to improve on this situation. The former group would obviously prefer the content to be just ported over to an MDN zone, for the MDN editors to have their wicked way with. The latter group have some reservations:
+* The Wiki on Github already has a dedicated community, who might get confused if it is suddenly uprooted and moved.
+* A lot of engineers prefer to write markdown and host on Github, rather than using a WYSIWYG tool like MDN.
+* They want Emscripten to stand up on its own as an independent project, and not be seen as Mozilla biased, which is a potential danger of putting it up on MDN.
+* We could put some content up on a dedicated Emscripten site, and then link to MDN for other content, but this might be a bit of a weird experience for users to go to the main Emscripten site, and then be put on a different site.
+Whatever happens, we need to put some content up on MDN anyway about Emscripten (which would probably be basic intro/hello world, writen in a different style so as not to duplicate the main site too much.) But it would be really amazing to be able to transclude some of the content from the Emscripten Wiki directly onto MDN, cutting out any needless duplication of content, and allowing the Emscripten contributors to write the docs their way and keep their separate site.
+We have already created a sample Emscripten zone at https://developer.mozilla.org/en-US/docs/Emscripten, to add test content to as we discuss this project, and the best way to proceed.
+==References==
 https://etherpad.mozilla.org/github-mdn
+https://wiki.mozilla.org/MDN/Development/GitBackend
+* This doesn't necessarily have to be an either-or thing - git vs wiki. We can look at moving the wiki to git, keep the current editor on MDN, while opening the content up to alternative editing styles via direct git access.