Jetpack/Porting to MDN

What we're doing

At the moment the docs are stored as Markdown files (with some extra bits of HTML) in the same GitHub repo as the SDK code. We're going to move them from there to developer.mozilla.org, which is a fancy Wiki.

Getting started

Sign into MDN

First, sign into MDN: https://developer.mozilla.org/. If you don't already have an account, MDN uses Persona, so you can just sign in with Persona, and if MDN doesn't recognize your email address it will prompt you to create an account.

Once you're signed in, add yourself to the beta users group if you're not already: go to your profile and check "beta users". You'll know if it worked because MDN will look nicer.

Then go to https://developer.mozilla.org/en-US/Add-ons/SDK. This is the new home page for the SDK docs. It should look pretty familiar: it has the same content as the current home page.

Check out the SDK

Check out the SDK repo from GitHub, activate and run cfx docs. If you have an existing checkout of the repo, please make sure you are on the master branch and that your master is up to date. We don't want to accidentally add old content!

Porting docs

Porting Tutorials

Tutorials are going to live here: https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials.

1. Run cfx docs.
2. Go to the Tutorials page (dev-guide/tutorials/index.html).
3. Pick a tutorial. Add its name to https://etherpad.mozilla.org/porting-addon-sdk-docs so noone else chooses it.
4. Go to https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials, select the little gear icon in the top-right, and choose "New sub-page".
5. In "Title" put the same thing the doc is called, like "Getting started with cfx". In "Slug" put the same thing as the document name, but replace dashes with underscores: "Getting-started-with-cfx" -> "Getting_started_with_cfx"
6. Below "Title" and "Slug" is a WYSIWYG editor, and that's how you edit stuff on MDN - it's where the article itself goes. You can click on the "Source" button to edit the HTML directly if you wish.

There are 2 ways you can copy the actual article: by default you get a WYSIWYG editor, and you can copy-paste HTML in there. The problem with that is that you'll get a lot of crap that you don't want (for example, IDs and classes for the syntax highlighter) and you'll have to trawl through the HTML to fix it properly. Ugh. Alternatively, you could just copy the text and add all the formatting manually. Ugh. Choose your poison. Maybe there's a better way.

You can do a fair amount with the WYSIWYG editor, including headings, special "Note" boxes, tables, preformatting and formatting as various different programming languages. If you need help with any of that, there's a guide: https://developer.mozilla.org/en-US/docs/Project:MDN/Contributing/Editor_guide/Editing or ask me.

1. Go through and fix all the internal links. Maybe we could automate this.
2. Back in https://etherpad.mozilla.org/porting-addon-sdk-docs, mark the doc as (done) so we know. Also, ping me to take a look.

Porting Guides

Just the same as tutorials, except we're getting them from dev-guide/guides/index.html and putting them in https://developer.mozilla.org/en-US/Add-ons/SDK/Guides.

Porting API reference docs

These are the docs that appear in the sidebar under "High-level APIs" and "Low level APIs". This is a bit more complicated because it's more structured information. I've written a guide specifically on that here: porting API pages.

It's possible we will write some macros to help make sure these pages are all consistent.

Extra bits and pieces

Multi-page articles

For multi-page articles, I think we should stick the main page under https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials, then sub-pages under the main page.

For example, for the Annotator we could have: https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Annotator containing https://addons.mozilla.org/en-US/developers/docs/sdk/Firefox-26/dev-guide/tutorials/annotator/index.html, then sub-pages like https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Annotator/Storing for each sub-page.

Dealing with images

For images:

1. Find them in your SDK installation at doc/static-files/media/.
2. Upload them to MDN by clicking "Attach Files" down at the bottom.
3. Then you can embed them in the article by clicking the button in the WYSIWYG editor just above the "B", and finding them in the dialog that appears.

If the image is big, make sure the "Width" and "Height" fields are empty, or the image will be distorted.

Usually I think centred images look nice. I do this by selecting the "Advanced" tab in the image-insertion dialog and pasting this" "display: block; margin-left: auto; margin-right: auto;" into the "Style" box.