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

532 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 128: / Line 135: @@
 === Docco ===
-[http://jashkenas.github.io/docco/ Docco] generates documentation from ["Literate Code" https://en.wikipedia.org/wiki/Literate_programming] and is starting to catch on in the JavaScript community:
+[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]
@@ Line 155: / Line 162: @@
 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.