769773 - Move API docs to MDN for discoverability

Status: RESOLVED FIXED

(Marketplace Graveyard :: API, defect)

Description

[Fred Wenzel [:wenzel]]

Now that the API is largely working, the Zamboni readthedocs is probably not the best spot to document it anymore, particularly because want it to be discoverable.

Janet: Can you suggest a spot for them to go?

Andy: Anything you'd like to add?

Comment 1

[Andy McKay]

I think we'll need to talk about oAuth, although perhaps @zalun sample app covers that.

I will add in docs for bug 769750 when I've got it done.

Comment 2

[Janet Swisher]

Are you planning to continue to maintain the docs in the source tree, and generate them with Sphinx? Because that workflow doesn't fit with MDN. Putting the docs into MDN is a one-way trip.

We've had this discussion previously for the Add-ons SDK, which opted to stay with Sphinx, because they need offline docs delivery. The Marketplace API doesn't have that requirement.

Whether or not you put the API docs into MDN, we can create a landing page for the API, which will help with discoverability, SEO, etc. The landing page would point to wherever the docs actually are.

Comment 3

[Janet Swisher]

And to answer your initial question, how about /en/Apps/Marketplace_API ?

Comment 4

[Fred Wenzel [:wenzel]]

I am fine with that location.

I'll defer to Andy on where to maintain them, but I do see the benefit of keeping them in MDN. Unfortunately that means docs changes can't be landed/reviewed together with code changes, but the added visibility and discoverability might be worth it.

What do you think Andy?

Comment 5

[Will Bamberg [:wbamberg]]

For the Add-on SDK, there's a plan to continue to maintain docs in the source repo (partly so they can be landed and reviewed alongside the code and with the same processes) but enable MDN's documentation system to extract them from the repo (for instance on a GitHub post-receive hook), build the HTML, and publish the result on MDN (partly to help with discoverability).

There's a bunch of discussion of that in bug 654918.

None of this would happen until after Kuma lands and the immediate post-Kuma tasks have been finished, so this might be too late for you. But it would be great if the requirements of products like this could be fed into Kuma development plans.

Comment 6

[Fred Wenzel [:wenzel]]

Can anyone help make this happen? I'd be fine with a relatively empty MDN page linking back to the Sphinx docs for now as a stopgap.

Comment 7

[Les Orchard [:lorchard]]

(In reply to Fred Wenzel [:wenzel] from comment #6)
> Can anyone help make this happen? I'd be fine with a relatively empty MDN
> page linking back to the Sphinx docs for now as a stopgap.

Maybe in a month or so, after we've gotten Kuma launched and stabilized. But, at the moment we're all pretty solidly occupied with that

Comment 8

[Les Orchard [:lorchard]]

(In reply to Fred Wenzel [:wenzel] from comment #6)
> Can anyone help make this happen? I'd be fine with a relatively empty MDN
> page linking back to the Sphinx docs for now as a stopgap.

Unless, of course, you want to make a wiki page with the above. In that case, anyone can do that now.

Comment 9

[Janet Swisher]

For now, I added a link to the Sphinx docs to the main apps page (https://developer.mozilla.org/en/Apps), in the Mozilla Marketplace section. When we have more content, we can think about making a landing page just for the API.

Comment 10

[Fred Wenzel [:wenzel]]

(In reply to Les Orchard [:lorchard] from comment #8)
> (In reply to Fred Wenzel [:wenzel] from comment #6)
> > Can anyone help make this happen? I'd be fine with a relatively empty MDN
> > page linking back to the Sphinx docs for now as a stopgap.
> 
> Unless, of course, you want to make a wiki page with the above. In that
> case, anyone can do that now.

Yeah that's what I meant.

(In reply to Janet Swisher from comment #9)
> For now, I added a link to the Sphinx docs to the main apps page
> (https://developer.mozilla.org/en/Apps), in the Mozilla Marketplace section.
> When we have more content, we can think about making a landing page just for
> the API.

Thanks, Janet. This should increase discoverability for now. (Obviously people still need our help, at the very least to create their API keys.)

Comment 11

[Wil Clouser [:clouserw]]

I'm closing this according to comment 9 and comment 10.  Not sure if there is more to do or not.