Closed Bug 654918 Opened 13 years ago Closed 11 years ago

Consider maintaining the add-on SDK documentation on MDN

Categories

(Add-on SDK Graveyard :: Documentation, defect, P1)

Product:
Add-on SDK Graveyard
Component:
Documentation
Type:
defect

Tracking

(Not tracked)

Status:
RESOLVED FIXED

People

(Reporter: clouserw, Assigned: wbamberg)

References

Details

This bug is a follow up to some discussions and, as something I can point to, bug 646500, comments 14+.

I think it would be most beneficial to have someone maintain the SDK documentation on MDN as the primary hosted site.  That gives us the benefit of having all the Mozilla docs in one place and being able to leverage their design, search, localization, etc.  Right now we're talking about hosting it at builder.addons.mozilla.org/docs/ which would make us have to reimplement all that work that we could get for free.
P1 to make the determination at least.
Assignee: nobody → dcm
OS: Linux → All
Priority: -- → P1
Hardware: x86 → All
Target Milestone: --- → 1.0
I had a discussion with Will and we came to the following conclusion: The SDK docs will live on the AMO Developer Hub until the long-term solution, moving the docs to MDN, is ready to go.

The Builder, as of the next release (0.9.5), will no longer house a copy of the docs. It will instead link to the main documentation wherever it is located. 

Fligtar was fine with the docs living on AMO temporarily. I am CCing him on the bug to ensure that everyone involved is in agreement.
awesome - I'm glad you guys talked about it. 

We should also try to remember that the spanish translation team is planning on translating the static docs - we should make sure the es_ES dir exists and it populated when they are done.
As I understand it:

- When 1.0 is finalized, someone builds the documentation as a bunch of flat files (how it's working now)
- They check that into a repository on github
- AMO will check that out onto disk somewhere on the webheads
- AMO will add an exception to the vhost in apache to serve that directory at a specific URL, separate from all the AMO code

That's fine for a release or so, but we should get a timeline for MDN.  For one thing, the above has no real support for L10n
Futured based on decision to do this in the future, but not for 1.0.
Target Milestone: 1.0 → Future
Whiteboard: [milestone:1.4]
Target Milestone: Future → 1.4
(Pushing all open bugs to the --- milestone for the new triage system)
Target Milestone: 1.4 → ---
Any ETAs for this bug?
We started a thread in email about the logistics in hosting this on MDN. Just found out about this bug, so I'll recap some of what I said in the thread.

The best thing for MDN would be if this documentation were in the wiki - we have already established processes there for community, software, and L10N.

But, these SDK docs already exist in Markdown and live in a github repo. So, there's an impedance mismatch with MDN.

So, with that in mind:

* this needs regular maintenance and can't just be a push-and-forget dump of static HTML.

* we need to manage updates without consuming webdev time and sprint points for every doc update.

* it would be great if it allowed authors and editors from the MDN community to participate - that's core to MDN

Some options to consider:

* we build a bridge between a git clone and the wiki API, sync changes to a set of wiki pages. Git commits change wiki pages, wiki edits trigger git commits

* we stick auto-generated docs somewhere like readthedocs.org and link from MDN

* we build our own readthedocs-alike and auto-push to MDN, triggered by github webhooks.
Also, have there been any discussions with regard to getting these docs skinned in a way that fits in with the rest of MDN?
Was there discussion about just writing the docs in wiki syntax instead of markdown?  That makes the docs accessible to the community (to edit, localize, etc.) and seems like the simplest option here.
(In reply to Wil Clouser [:clouserw] from comment #10)
> Was there discussion about just writing the docs in wiki syntax instead of
> markdown?  That makes the docs accessible to the community (to edit,
> localize, etc.) and seems like the simplest option here.

That'd be the simplest for MDN, but I think we'd assumed that was the worst case for the current SDK docs.
(In reply to Les Orchard [:lorchard] from comment #9)
> Also, have there been any discussions with regard to getting these docs
> skinned in a way that fits in with the rest of MDN?

Yup.  We need to preserve the layout, but will need to update the style to match MDN.
(In reply to Les Orchard [:lorchard] from comment #11)
> (In reply to Wil Clouser [:clouserw] from comment #10)
> > Was there discussion about just writing the docs in wiki syntax instead of
> > markdown?  That makes the docs accessible to the community (to edit,
> > localize, etc.) and seems like the simplest option here.
> 
> That'd be the simplest for MDN, but I think we'd assumed that was the worst
> case for the current SDK docs.

Ideally they would be in the wiki but the SDK requires them to be in Github since they also package docs into the SDK itself.  Until that dependency changes we need to find a creative solution for Github<->Kuma docs.
(In reply to Wil Clouser [:clouserw] from comment #10)
> Was there discussion about just writing the docs in wiki syntax instead of
> markdown?  That makes the docs accessible to the community (to edit,
> localize, etc.) and seems like the simplest option here.

Rewriting the docs to use wiki syntax would be simple. But there are some features that the SDK's doc system currently offers that would be lost if we did that.

1) offline operation: at the moment the docs ship with the SDK

2) docs are always synced with the code: if you ask for the docs from an SDK installation, you always get the version of the docs matching that version of the SDK. This doesn't necessarily require offline operation.

3) integrated docs for community-developed packages: if you extend the SDK by writing a new package, and document it with some Markdown files for it, then a user can drop your package into the SDK install and its documentation will show up in the docs browser.

4) structured API docs: at the moment the API docs uses a structured (horrible, nonstandard) syntax, which ensures that all APIs are documented consistently, and enables the tools to generate JSON for the APIs, which in turn enables IDEs to support stuff like code completion. Having said that, I don't know of anyone actually using the JSON right now, although I think the Add-on Builder is intending to add code completion.

5) in-source API docs: following on from that, there's a requirement, not yet implemented, to support in-source documentation for the API docs, probably using YUIDoc format.

We need to either work out how to support features like this with the wiki, or decide that they're not important enough to be worth saving. The feedback I've had suggests that they are important enough to be worth saving.
(In reply to Will Bamberg [:wbamberg] from comment #14)

TL;DR: This makes me think that github<->wiki sync idea is a dead end.

If docs are embedded in the source, then replicating on-wiki edits back to those docs will be impractical. What we're probably in need of is our own system like readthedocs.org as a parallel universe of published docs alongside the wiki.

More comments inline:

> Rewriting the docs to use wiki syntax would be simple. But there are some
> features that the SDK's doc system currently offers that would be lost if we
> did that.
> 
> 1) offline operation: at the moment the docs ship with the SDK

Depends on what you mean by "offline". We're considering HTML5 offline manifests and such for the wiki, and possibly the ability to build a shopping cart of pages to bundle up for download.

> 2) docs are always synced with the code: if you ask for the docs from an SDK
> installation, you always get the version of the docs matching that version
> of the SDK. This doesn't necessarily require offline operation.

Does this imply that we should be maintaining and serving up per-version docs from MDN?

> 3) integrated docs for community-developed packages: if you extend the SDK
> by writing a new package, and document it with some Markdown files for it,
> then a user can drop your package into the SDK install and its documentation
> will show up in the docs browser.

By docs browser, do you mean something on MDN? Or is this like a localhost web server you could spin up from the SDK?

> 4) structured API docs: at the moment the API docs uses a structured
> (horrible, nonstandard) syntax, which ensures that all APIs are documented
> consistently, and enables the tools to generate JSON for the APIs, which in
> turn enables IDEs to support stuff like code completion. Having said that, I
> don't know of anyone actually using the JSON right now, although I think the
> Add-on Builder is intending to add code completion.

Does this translate into MDN functionality?

> 5) in-source API docs: following on from that, there's a requirement, not
> yet implemented, to support in-source documentation for the API docs,
> probably using YUIDoc format.

This requirement would make bidirectional edits between SDK docs and the wiki impractical.

> We need to either work out how to support features like this with the wiki,
> or decide that they're not important enough to be worth saving. The feedback
> I've had suggests that they are important enough to be worth saving.

So, this is what makes me think we need our own readthedocs.org. We need some system that will maintain fresh published copies of docs generated from source and markdown files that live in the project repo. Community editors won't be able to edit them like they do the wiki, but they can issue pull requests to the project. So, it wouldn't be entirely exclusive
> 
> > 2) docs are always synced with the code: if you ask for the docs from an SDK
> > installation, you always get the version of the docs matching that version
> > of the SDK. This doesn't necessarily require offline operation.
> 
> Does this imply that we should be maintaining and serving up per-version
> docs from MDN?

At the moment a set of docs for each release is hosted online:

https://addons.mozilla.org/en-US/developers/docs/sdk/1.2/
https://addons.mozilla.org/en-US/developers/docs/sdk/1.1/
https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/

For the local/offline version, the doc source is maintained alongside the code, so the version of the docs just matches the version of the code. Actually, I'd be very happy for the latest version of the docs to be available online as well. A readthedocs-style approach like you suggested would do that well, and would also be able to cope with versions, since the SDK releases are tagged in GitHub.
 
> > 3) integrated docs for community-developed packages: if you extend the SDK
> > by writing a new package, and document it with some Markdown files for it,
> > then a user can drop your package into the SDK install and its documentation
> > will show up in the docs browser.
> 
> By docs browser, do you mean something on MDN? Or is this like a localhost
> web server you could spin up from the SDK?

Something like the latter. Actually just a Python script that generates the HTML from the source, and runs the browser pointed at a file:// URL.

> > 4) structured API docs: at the moment the API docs uses a structured
> > (horrible, nonstandard) syntax, which ensures that all APIs are documented
> > consistently, and enables the tools to generate JSON for the APIs, which in
> > turn enables IDEs to support stuff like code completion. Having said that, I
> > don't know of anyone actually using the JSON right now, although I think the
> > Add-on Builder is intending to add code completion.
> 
> Does this translate into MDN functionality?
> 
> > 5) in-source API docs: following on from that, there's a requirement, not
> > yet implemented, to support in-source documentation for the API docs,
> > probably using YUIDoc format.
> 
> This requirement would make bidirectional edits between SDK docs and the
> wiki impractical.
> 
> > We need to either work out how to support features like this with the wiki,
> > or decide that they're not important enough to be worth saving. The feedback
> > I've had suggests that they are important enough to be worth saving.
> 
> So, this is what makes me think we need our own readthedocs.org. We need
> some system that will maintain fresh published copies of docs generated from
> source and markdown files that live in the project repo. 

The code that generates the HTML from the source is of course already written, as it runs in the SDK to build the local version of the docs. You'd just need something to pull the right version from GitHub (triggered by a post-receive hook?) and push the generated HTML to the right place.

> Community editors
> won't be able to edit them like they do the wiki, but they can issue pull
> requests to the project. So, it wouldn't be entirely exclusive

That's a shame, yes. One of the things I dislike about the current doc system is that it's too hard to contribute fixes. Although community members can and do issue pull requests right now, so it's not exactly exclusive. Just harder to use :(.
(In reply to Will Bamberg [:wbamberg] from comment #16)

> At the moment a set of docs for each release is hosted online:

So, whatever we do, it should support this. Maybe this translates to a configured list of git branches to watch and one marked as current for the latest docs.

> The code that generates the HTML from the source is of course already
> written, as it runs in the SDK to build the local version of the docs. You'd
> just need something to pull the right version from GitHub (triggered by a
> post-receive hook?) and push the generated HTML to the right place.

The "just" part of any project is where the fun happens :)

But yeah, we would build something that responds to a post-receive hook. That would kick off HTML generation and then deploy the results to all the front-end hosts. So, a limited version of what we do for code pushes.

Depending on how security paranoid we want to be, that might have to be a post-receive hook on a Mozilla-controlled git repo, rather than responding to a GitHub hook directly. (ie. if GitHub gets hacked, let's not blindly deploy to Mozilla servers.)

And, for deployment, we'll need to have a chat with IT folks to suss out the flow. They currently use git to track & deploy assets to front-ends, but it's a process not directly mapped to the git repos for our source. We'd build a bridge between the two.

> > Community editors
> > won't be able to edit them like they do the wiki, but they can issue pull
> > requests to the project. So, it wouldn't be entirely exclusive
> 
> That's a shame, yes. One of the things I dislike about the current doc
> system is that it's too hard to contribute fixes. Although community members
> can and do issue pull requests right now, so it's not exactly exclusive.
> Just harder to use :(.

We should do some thinking about this, but I think it's the tradeoff between having docs close to the code (and probably more likely to be current) vs docs wrapped in convenient editing tools.
(In reply to Les Orchard [:lorchard] from comment #17)
> Depending on how security paranoid we want to be, that might have to be a
> post-receive hook on a Mozilla-controlled git repo, rather than responding
> to a GitHub hook directly. (ie. if GitHub gets hacked, let's not blindly
> deploy to Mozilla servers.)

We want to be security paranoid and have a medium-term plan to make a Mozilla-controlled Git repository the canonical repository for Add-on SDK code (while retaining the GitHub repository as our center for collaboration/reviews/etc.).
Not that I want to make this conversation even more complicated... but bear in mind that at some point (2012 Q1? Q2?) we'll probably migrate some (many? all?) of the SDK API modules from the SDK repository to the Firefox repository (mozilla-central and its branch repositories) and ship them in core Firefox, at which point their docs will probably migrate there too.

But we'll still want to present a "unified front" of documentation that describes the functionality available to users of the SDK, including those APIs in core Firefox, any APIs that ship with the SDK itself; the non-API functionality of the SDK (in particular, its command-line tool for running, testing, and packaging addons); and the tutorials, guides, examples, etc. targeted to SDK users.
Whatever you guys do, just please make sure it doesn't affect the nice properties Will mentions in comment 14, especially points 1 to 3, which are foundational to building a healthy community of third-party SDK developers that may yet form someday.  If the docs really must be on MDN, just pick them up and move them from AMO (keeping Myk's "unified front"), restyle them if you have to, but keep them static.  Let a separate wikified area serve as a community-maintained knowledge base, which is what MDN is good at anyway.  People can always make project contributions like documentation by filing bugs and pull requests.
(In reply to Drew Willcoxon :adw from comment #20)
> If the docs really must be on MDN, just pick
> them up and move them from AMO (keeping Myk's "unified front"), restyle them
> if you have to, but keep them static. 
>
> Let a separate wikified area serve as
> a community-maintained knowledge base, which is what MDN is good at anyway. 
> People can always make project contributions like documentation by filing
> bugs and pull requests.

That's why I say we need our own readthedocs.org workalike - because I don't expect the Addon SDK will be the last project that wants doco done like this.

We can keep these generated docs distinct from the wiki, build navigation from the rest of the site, wrap them in the right update processes, include them in our search indexing, and make sure we've covered the messaging and contribution flows.

Basically, I want to see us do it right and not just unpack a tarball at developer.mozilla.org because it's a nice domain name :)
Depends on: 690449
(In reply to Les Orchard [:lorchard] from comment #17)
> (In reply to Will Bamberg [:wbamberg] from comment #16)
> 
> The "just" part of any project is where the fun happens :)
> 

Sorry, it slipped out! :-o I've doomed the whole thing now, haven't I.

> > That's a shame, yes. One of the things I dislike about the current doc
> > system is that it's too hard to contribute fixes. Although community members
> > can and do issue pull requests right now, so it's not exactly exclusive.
> > Just harder to use :(.
> 
> We should do some thinking about this, but I think it's the tradeoff between
> having docs close to the code (and probably more likely to be current) vs
> docs wrapped in convenient editing tools.

Exactly. And it's not certain that the SDK has made the right choice here. I'd also be interested in knowing whether there's been any interest in using in-source docs for analogous reference material: the XPCOM documentation for example.

(In reply to Drew Willcoxon :adw from comment #20)
> Whatever you guys do, just please make sure it doesn't affect the nice
> properties Will mentions in comment 14, especially points 1 to 3, which are
> foundational to building a healthy community of third-party SDK developers
> that may yet form someday.

Agreed, but this proposal does, if I understand it, keep all those nice properties. It also adds some extra ones, like having up-to-date versions of the docs online. I think it sounds really promising.

(In reply to Myk Melez [:myk] [@mykmelez] from comment #19)
> Not that I want to make this conversation even more complicated... but bear
> in mind that at some point (2012 Q1? Q2?) we'll probably migrate some (many?
> all?) of the SDK API modules from the SDK repository to the Firefox
> repository (mozilla-central and its branch repositories) and ship them in
> core Firefox, at which point their docs will probably migrate there too.
> 
> But we'll still want to present a "unified front" of documentation that
> describes the functionality available to users of the SDK, including those
> APIs in core Firefox, any APIs that ship with the SDK itself; the non-API
> functionality of the SDK (in particular, its command-line tool for running,
> testing, and packaging addons); and the tutorials, guides, examples, etc.
> targeted to SDK users.

I am a bit worried about Myk's comment 19. Lots of questions. But I feel as if we should treat it as an independent problem, rather than trying to work out its implications now.

(In reply to Les Orchard [:lorchard] from comment #21)
> (In reply to Drew Willcoxon :adw from comment #20)
> > If the docs really must be on MDN, just pick
> > them up and move them from AMO (keeping Myk's "unified front"), restyle them
> > if you have to, but keep them static. 
> >
> > Let a separate wikified area serve as
> > a community-maintained knowledge base, which is what MDN is good at anyway. 
> > People can always make project contributions like documentation by filing
> > bugs and pull requests.
> 
> That's why I say we need our own readthedocs.org workalike - because I don't
> expect the Addon SDK will be the last project that wants doco done like this.
> 

I'm also really interested in other projects that might have similar requirements. Building something like this only for the sake of the SDK seems less worthwhile, and I'd be very happy if it could have a more general application.
This is something the docs team has been talking about for some time. We'd like to build out a tool for making it easy for writers to compose documentation whose source is kept in the comments of IDL code, for example, edited WYSIWYG, then output as diffs for checking into the tree. Ideally, some kind of trusted tool would exist that would automatically check in comments-only changes like these, so that writers could work without being bottlenecked by the usual review process.
(In reply to Will Bamberg [:wbamberg] from comment #22)
> I am a bit worried about Myk's comment 19. Lots of questions. But I feel as
> if we should treat it as an independent problem, rather than trying to work
> out its implications now.

I totally agree!  Even if it creates more work overall, tackling these problems separately is more likely to be successful than trying to satisfy all their requirements all at once (especially given that one of them is currently theoretical).


> I'm also really interested in other projects that might have similar
> requirements. Building something like this only for the sake of the SDK
> seems less worthwhile, and I'd be very happy if it could have a more general
> application.

Me too!  However, I recommend you focus on solving the SDK's problems specifically and then potentially generalize the specific solution, as that approach tends to be more successful than trying to pre-generalize it.
Any ETAs on this?  If it's not any time soon we may need to alter the way we're doing docs on the SDK aside from this.
(In reply to Wil Clouser [:clouserw] from comment #25)
> Any ETAs on this?  If it's not any time soon we may need to alter the way
> we're doing docs on the SDK aside from this.

I can't say how long the change Les has proposed here would take, but it won't happen for the 1.4 release in the middle of January, and most likely not for the 1.5 release at the end of February either.
(In reply to Wil Clouser [:clouserw] from comment #25)
> Any ETAs on this?  If it's not any time soon we may need to alter the way
> we're doing docs on the SDK aside from this.

No ETA. It's not even really on our radar to get done, yet

(In reply to Will Bamberg [:wbamberg] from comment #26)
> (In reply to Wil Clouser [:clouserw] from comment #25)
> > Any ETAs on this?  If it's not any time soon we may need to alter the way
> > we're doing docs on the SDK aside from this.
> 
> I can't say how long the change Les has proposed here would take, but it
> won't happen for the 1.4 release in the middle of January, and most likely
> not for the 1.5 release at the end of February either.

I would be surprised if we had a good answer for this before the end of 2012Q1, since we're pretty stacked with work through then. I mean, we could just punt and unpack a tarball in a directory and call this done, but I wouldn't want that to turn into legacy we need to support because we didn't do it right to begin with
We're kicking over to KUMA for MDN - is it time to revisit this bug?
(In reply to Jeff Griffiths from comment #28)
> We're kicking over to KUMA for MDN - is it time to revisit this bug?

Not yet, no. Maybe in a month or two. We need a chance to actually launch & stabilize Kuma first.
(In reply to Les Orchard [:lorchard] from comment #29)
> (In reply to Jeff Griffiths from comment #28)
> > We're kicking over to KUMA for MDN - is it time to revisit this bug?
> 
> Not yet, no. Maybe in a month or two. We need a chance to actually launch &
> stabilize Kuma first.

Les, I disagree - there is no reason not to start planning this now, on the Jetpack side. This doesn't mean we will have anything to implement right away, but in 'a month or two' when we can look at this, I'd like to have a solid plan to look at rather than this being the point that we 8start* planning.
(In reply to Jeff Griffiths from comment #30)
> (In reply to Les Orchard [:lorchard] from comment #29)
> > (In reply to Jeff Griffiths from comment #28)
> > > We're kicking over to KUMA for MDN - is it time to revisit this bug?
> > 
> > Not yet, no. Maybe in a month or two. We need a chance to actually launch &
> > stabilize Kuma first.
> 
> Les, I disagree - there is no reason not to start planning this now, on the
> Jetpack side. This doesn't mean we will have anything to implement right
> away, but in 'a month or two' when we can look at this, I'd like to have a
> solid plan to look at rather than this being the point that we 8start*
> planning.

The reason I say not yet is because the MDN team isn't ready to help with any input, and we're not sure what kind of implementation will be possible. I mean, you want us to help host & manage the content, right? We're right in the middle of the relaunch right now, and things are very much in flux.
Adding a couple people who should probably be tracking this
Thanks for letting us know, Les.

Les makes a good point that the development team will be very busy polishing up Kuma over the next couple of months, and Jeff makes a good point that it would ideal to have the documentation online sooner than later. The two goals don't need to be mutually exclusive, so I'm sure we can reach a good compromise that makes everyone pretty happy.

Let's talk about this at dinner tonight and update this bug afterwards.
Reassigning this bug to Will Bamberg who will ultimately make the call and the switch
Assignee: dcm → wbamberg
Considered, and done: https://developer.mozilla.org/en-US/Add-ons/SDK.
Status: NEW → RESOLVED
Closed: 11 years ago
Resolution: --- → FIXED
This is a big deal, and I'm really excited that this is done. Thanks to :wbamberg in particular but to everyone that made this happen!
You need to log in before you can comment on or make changes to this bug.