779590 - Obsolete SDK docs should point people at the latest version

Status: RESOLVED FIXED

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

Description

[Will Bamberg [:wbamberg]]

Search engines usually return old versions of the SDK docs. We should ensure that people navigating to old versions of the docs are told that these versions are obsolete, and given a chance to navigate to the latest version.

Comment 2

[Will Bamberg [:wbamberg]]

So I can think of a couple of approaches to this.

1) The manual approach: whenever we publish a new set of SDK docs on AMO, we also update the previous set to include a deprecation message.

2) The automatic approach: when we load a page of the SDK docs, fetch /latest/index.html and look at its version: if this is higher than the current page, display a deprecation message.

Either way, we would need a manual step to fix all the old versions on AMO, that don't have either approach implemented.

Any opinions on which one to prefer? I don't like (1) because it adds another manual step to the release process. On the other hand, (2) means an extra GET whenever we load a page.

Comment 3

[Jeff Griffiths (:canuckistani) (:⚡︎)]

I also wonder about what range of previous docs we should keep - perhaps 2-3 versions would be good.

So, in this case, what we could do is, when shipping 1.10 ( for example ):

1. generate docs for 1.8.2, 1.9 & 1.10 ( we could automate this to be produced by a single command ). In this scenario 1.8.2 and 1.9 would contain deprecation warnings.

2. provide all three sets of docs as a package to AMO to be deployed, replacing everything that was there before.

The one problem I can see with this is it might limit our ability to put release bits in place early as we are currently doing, and I really like doing that.

I instinctively dislike option 2) for one main reason, that it seems it would rely on client side JS.

Comment 4

[Will Bamberg [:wbamberg]]

Wil: are you OK with a plan like the one Jeff's suggested in comment 3 above? 

> I instinctively dislike option 2) for one main reason, that it seems
> it would rely on client side JS.

It's not the only thing that relies on client side JS, or the most important, probably. But I can understand the desire to limit this dependency.

Comment 5

[Wil Clouser [:clouserw]]

If the requirement is still that these can be distributed and need to run entirely client side, then the two solutions in comment 2 are all I can think of also.  Both have their drawbacks - I'd probably work on automating #1 with some fancy scripts.

Regarding comment 3, I really like the idea of reducing the number of versions we have laying around.  Thumbs up on that.  As far as how we do it, I don't understand the "package to AMO" plan - what is a package there.  An RPM?

And just for the record, we're deprecating our current /vendor/ model (where we check out versions of code to our /vendor/ directory).  We're moving towards maintaining everything with pip packages or RPMs.  I don't know how that affects the docs yet, but things will be changing.

Comment 6

[Will Bamberg [:wbamberg]]

(In reply to Wil Clouser [:clouserw] from comment #5)
> 
> Regarding comment 3, I really like the idea of reducing the number of
> versions we have laying around.  Thumbs up on that. 

What would happen if users navigated to old versions no longer hosted? Could they be redirected somewhere helpful?

> As far as how we do it,
> I don't understand the "package to AMO" plan - what is a package there.  An
> RPM?

Not an RPM, no: just the same as now, a git repo at a specified tag. The difference being that instead of adding the contents of the repo to a new location under https://addons.mozilla.org/en-US/developers/docs/sdk/, the contents of the repo completely replaces everything under https://addons.mozilla.org/en-US/developers/docs/sdk/.

That's easiest for me. But I'm happy to think about other delivery vehicles for this, if it'll make your life easier.

> And just for the record, we're deprecating our current /vendor/ model (where
> we check out versions of code to our /vendor/ directory).  We're moving
> towards maintaining everything with pip packages or RPMs.  I don't know how
> that affects the docs yet, but things will be changing.

OK, just let me know what the impact is as soon as you do, please.

Comment 7

[Wil Clouser [:clouserw]]

(In reply to Will Bamberg [:wbamberg] from comment #6)
> (In reply to Wil Clouser [:clouserw] from comment #5)
> > 
> > Regarding comment 3, I really like the idea of reducing the number of
> > versions we have laying around.  Thumbs up on that. 
> 
> What would happen if users navigated to old versions no longer hosted? Could
> they be redirected somewhere helpful?

We could add a redirect in nginx.  That's something you'd have to do every release with IT (or potentially it could cover a range, but within the constraints of regex).


> > As far as how we do it,
> > I don't understand the "package to AMO" plan - what is a package there.  An
> > RPM?
> 
> Not an RPM, no: just the same as now, a git repo at a specified tag. The
> difference being that instead of adding the contents of the repo to a new
> location under https://addons.mozilla.org/en-US/developers/docs/sdk/, the
> contents of the repo completely replaces everything under
> https://addons.mozilla.org/en-US/developers/docs/sdk/.
> 
> That's easiest for me. But I'm happy to think about other delivery vehicles
> for this, if it'll make your life easier.

I still don't quite understand how that would work, but if it's easy for you I'm interested to know more.  The SDK docs are in a completely independent repo now and we can do anything we want to them: https://github.com/mozilla/addon-sdk-sdocs-pub


> > And just for the record, we're deprecating our current /vendor/ model (where
> > we check out versions of code to our /vendor/ directory).  We're moving
> > towards maintaining everything with pip packages or RPMs.  I don't know how
> > that affects the docs yet, but things will be changing.
> 
> OK, just let me know what the impact is as soon as you do, please.

As mentioned above, the SDK docs live in their own repo now and are completely disconnected from the AMO repository so the pressure I was feeling above is gone since developers don't have to deal with all the versions.  I'm happy to help make things better for you but it's no longer something I'm going to be bugging you about. :)

Comment 8

[Will Bamberg [:wbamberg]]

done:
https://addons.mozilla.org/en-US/developers/docs/sdk/1.9/dev-guide/index.html
https://addons.mozilla.org/en-US/developers/docs/sdk/1.10/dev-guide/index.html