Retiring "cfx docs"?

[Will Bamberg]

I've been thinking a bit about what will happen to the SDK documentation once we stop shipping modules in the downloaded bit of the SDK.

For context, here's the current status and next steps for the SDK:

* SDK APIs are currently in Firefox 21 (as of yesterday, the Firefox Beta)
* these APIs are the same as the APIs in SDK 1.14
* SDK 1.14 is the last SDK release that will include the APIs
* at some point, tbd, there will be an SDK 1.15, consisting only of cfx
* Firefox 22 (shipping June 25) will be the first version in which the SDK APIs shipping in Firefox will diverge from the APIs shipped in SDK 1.14

I think we should from now on stop shipping the docs in the downloadable SDK. There are two reasons for this:

1) the SDK docs need to track the APIs: but if the downloadable SDK doesn't release in sync with Firefox any more, and the APIs are in Firefox, then they can't
2) the SDK doc generator uses the modules for various things (primarily metadata) so expects them to be present

This means that on June 25, or a few weeks earlier, we should publish the "Firefox 22" release of the SDK docs, which documents the APIs in Firefox 22 as well as the corresponding version of cfx.

We should disentangle the doc generation code from cfx, and retire cfx docs (or cfx docs could just launch a browser pointed at the online docs, if that's desirable).

Where should we publish these docs? At the moment they get published to addons.mozilla.org. For a long time we've wanted to publish them to developer.mozilla.org, and that's still the goal[1]. But I think that's unlikely to happen before June 25, so it's likely that the docs will stay on addons.mozilla.org for a little while yet.

Is it an important requirement that people with a clone of the SDK repo should be able to generate docs directly from that version of the code?

I'd be happy to hear any comments about any of this.

Will

[1] Specifically, I'm thinking of making the SDK docs into a Sphinx-compatible docset: then readthedocs.org will just work with it, and MDN can integrate it by just specifying a CNAME  to define the URLs at which the docs are served (as I understand things...)

[Myk Melez]

On 2013/04/03 10:22, Will Bamberg wrote:

We should disentangle the doc generation code from cfx, and retire cfx docs (or cfx docs could just launch a browser pointed at the online docs, if that's desirable).

FWIW, I don't find myself using cfx docs these days. It's easier and faster to google for "addon sdk [thing I'm looking for]" and click through to the right page in the online version of the docs.

Where should we publish these docs? At the moment they get published to addons.mozilla.org. For a long time we've wanted to publish them to developer.mozilla.org, and that's still the goal[1]. But I think that's unlikely to happen before June 25, so it's likely that the docs will stay on addons.mozilla.org for a little while yet.

If you can separate this concern, then it's worth doing so, so you only have to tackle one of these hairy problems at a time. :-)

Is it an important requirement that people with a clone of the SDK repo should be able to generate docs directly from that version of the code?

It would be useful, but I'm still not sure how important it is. I do occasionally find myself missing a way to read generated docs for a module I'm using from a repository clone (of the SDK or a third-party module). But I don't have the need very often. And when I do, it suffices to locate and open the Markdown document in my text editor.

That might not work as well for non-module docs, like tutorials, for which it isn't as obvious where to find the Markdown document in my clone. For example, I recently needed to read Listening for Load and Unload to refamiliarize myself with exports.onUnload. And I read the online version, which could theoretically have caused me some grief if the functionality changed between the version documented online and the version in my clone.

But even then I probably could have located the Markdown document without too much trouble if I'd bothered to do so.

I'd be happy to hear any comments about any of this.

Generally speaking, I would optimize for maintainability, even at the cost of some usability. I'd rather have access to the most comprehensive, up-to-date documentation in one location (i.e. online) than multiple ways to read information that you don't have as much time to update because you're busy writing code to make it available in multiple locations.

In a world where engineering resources are a constraint, and we can't meet every need while meeting any of them well, focusing on the most important ones is crucial!

-myk

[Erik Vold]

Do it! kill that python..  DMO seems like the right place to me.

Erik

--
You received this message because you are subscribed to the Google Groups "mozilla-labs-jetpack" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mozilla-labs-jet...@googlegroups.com.
To post to this group, send email to mozilla-la...@googlegroups.com.
Visit this group at http://groups.google.com/group/mozilla-labs-jetpack?hl=en-US.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[ZER0]

On 4/3/13 7:22 PM, Will Bamberg wrote:

[cut]

> I think we should from now on stop shipping the docs in the downloadable
> SDK. There are two reasons for this:

Is that means that the github repo won't contain the MD file anymore?

> Where should we publish these docs? At the moment they get published to
> addons.mozilla.org

> <https://addons.mozilla.org/en-US/developers/docs/sdk/latest/dev-guide/index.html>.

> For a long time we've wanted to publish them to developer.mozilla.org

> <https://developer.mozilla.org/>, and that's still the goal[1]. But I

> think that's unlikely to happen before June 25, so it's likely that the
> docs will stay on addons.mozilla.org for a little while yet.

> Is it an important requirement that people with a clone of the SDK repo
> should be able to generate docs directly from that version of the code?

To me, it's quite important have the docs as local/offline of the API
I'm currently using; because sometimes I'm working without internet
connection.

I'd like the idea of splitting the docs generation from the cfx, as far
as there is still a tool or an easy way to have them locally somehow.

[Will Bamberg]

On 13-04-04 9:07 AM, ZER0 wrote:
> On 4/3/13 7:22 PM, Will Bamberg wrote:
>
> [cut]
>> I think we should from now on stop shipping the docs in the downloadable
>> SDK. There are two reasons for this:
> Is that means that the github repo won't contain the MD file anymore?

No, it means that the downloadable, officially released SDK tarball
won't contain the MD files. For the time being, at least, and possibly
for ever, the doc source will still live in GitHub as a collection of MD
files.

>
>> Where should we publish these docs? At the moment they get published to
>> addons.mozilla.org
>> <https://addons.mozilla.org/en-US/developers/docs/sdk/latest/dev-guide/index.html>.
>> For a long time we've wanted to publish them to developer.mozilla.org
>> <https://developer.mozilla.org/>, and that's still the goal[1]. But I
>> think that's unlikely to happen before June 25, so it's likely that the
>> docs will stay on addons.mozilla.org for a little while yet.
>> Is it an important requirement that people with a clone of the SDK repo
>> should be able to generate docs directly from that version of the code?
> To me, it's quite important have the docs as local/offline of the API
> I'm currently using; because sometimes I'm working without internet
> connection.
>
> I'd like the idea of splitting the docs generation from the cfx, as far
> as there is still a tool or an easy way to have them locally somehow.
>
>

The GitHub repo will still include a tool for generating the HTML from
the doc source, since that's what I'll use to build the docs for
releases. It will be a lot like the existing cfx docs, although it might
take a couple of extra arguments for things that it won't be able to get
from cfx any more.

Will

[Erik Vold]

You'll basically fork the addon-sdk repo, and cut out anything that isn't doc related?

Then we can remove doc related stuff from the addon-sdk too, right?

Erik

[Jeff Griffiths]

I think the idea is to maintain everything from a single github repo, so we don't change how contributions are made. The real changes here are:

* where things get published to ( AMO is a terrible publishing target IMO )
* some layout changes in the repo?

The important thing to me is to make sure the docs are available as possible. I see our ability to take contributions via a single github  repo as being a key strength, I don't want to mess with that.

Jeff

[Erik Vold]

Hmm,

What if we just started integrating with MDN and document the sdk the same way that everything else in m-c is documented?

Erik

[Will Bamberg]

On 13-04-10 1:56 PM, Erik Vold wrote:

Hmm,

What if we just started integrating with MDN and document the sdk the same way that everything else in m-c is documented?

Erik

Well, we could, if we think that's the best thing to do.

What we gain:
* accessibility: easier for anyone to edit the SDK docs
* discoverability: docs are in the same place as the other docs, they look the same as the other docs
* maintainability: we don't have to maintain a system for building and publishing the docs
* access to MDN's localization tools and community

What we lose:
* an easy way to ensure that the docs and the code stay approximately in sync, and to indicate which version of the docs is for which version of the code
* control over the way the docs can be laid out, sidebars and stuff
* any possibility of including docs from the source code, including metadata like stability and application compatibility
* the use of tools like GitHub for reviewing docs

Across Mozilla teams generally, there's increasing interest in using GitHub for documentation as well as code, and there's talk of enabling MDN to integrate documentation which is stored in GitHub-hosted repos, and there's also talk of Jetpack being a prototype for this. But I don't think this is likely to happen terribly quickly.

I'm happy for us to just copy the docs content into the MDN wiki, as long as we're making an informed decision about it.

Will

[Erik Vold]

I do like the fact that documentation has to be reviewed, which is also a quality check.

This is a tough one..

Getting our stuff on MDN seems important to me too though, since we are in m-c now, and MDN only talks about bootstrapped add-ons as if jetpacks don't exist.

Erik

[Hernan Rodriguez Colmeiro]

On Wed, Apr 10, 2013 at 6:44 PM, Erik Vold <erik...@gmail.com> wrote:
> Getting our stuff on MDN seems important to me too though, since we are in
> m-c now, and MDN only talks about bootstrapped add-ons as if jetpacks don't
> exist.
>

That's true, better exposure wouldn't hurt, but I don't know if I'd
like that the entire documentation was moved to MDN, unless what Will
said earlier comes true. Another issue I tink wasn't mentioned is that
MDN is quite... uncomfortable, for writing docs. And not markdown
compatible as far as I know.

Maybe what can be done is move the tutorials from the SDK docs over to
MDN, but leave the actual documentation (the reference part) outside.
Not sure where that "outside" would be though.

Hernán

[Jeff Griffiths]

To be clear: I think it would be *awesome* to have the Jetpack docs on developer.mozilla.org. I'd even go so far as to say that I think some material could be maintained in the wiki.

What I would instead like for most of the docs is some part of MDN carved out that has the current version of our docs, access to previous versions of our docs, and some verbiage that explains how to contribute to those docs.

The tricky part is, I then want it to be easy to add supplementary articles into the wiki that enhance all of this more static stuff, so that anyone can add in specific examples of how to use the SDK.

Jeff

[Will Bamberg]

I've had a response off-list, asking that we keep an option for a developer to have the docs locally.

Here's what this proposal says about that:

* you'll still be able to generate a local copy of the docs by cloning the repo and running a Python command which will be pretty similar to the current "cfx docs"

* the downloadable bit of the SDK will no longer ship with any docs in it

* when the SDK docs start getting published to MDN, we'll include a feature to download them as a single zip file, for offline operation. Thanks for pointing that out, it's a good requirement that I had forgotten about.

I'm happy to talk about other approaches if this doesn't seem OK. But as I've said below, given the decoupling of the downloadable part of the SDK (basically just cfx) from the SDK modules themselves, it doesn't really make sense for the downloadable part of the SDK to contain documentation for the modules.

Will