Re: Documentation URLs

[Michael . Schroepl]

> As we hope, maybe, some day soon, to move into the 2.2 branch, and then,
> some day, 2.4, and so on, we're going to continue to face the challenge
> of what the URLs for the documentation should be. Having docs-2.0,
> docs-2.2, docs-2.4, etc, is sucky and not scalable.

I'd say it depends. Therefore my first question would be: Do you intend to keep the Apache 1.3 and 2.0 documentation forever?

If yes (that's what I would want to, maybe some day including a note that its maintenance has expired) then URLs like those you named are required.
Which of course doesn't mean these URLs should be the only ones - yet they would allow foreign servers to refer to any version dependent information without significant danger of link rot. (For example, mod_gzip isn't likely to play any significant role in the Apache 2.x world, so if I ever want to link to the Apache documentation it would very likely be the 1.3 version, and hopefully using an URL that won't ever change. Of course I'd prefer to use /docs-1.3/ for that, as to make the version dependence clear.)

> How about ...
>
> /docs-stable/  -- Current released version (2.0 now)
> /docs-dev/     -- Current development version (2.1 now)j

That's what I would do _additionally_ to the URLs you mentioned above.
Therefore you would have stable URLs about version numbers _and_ dynamic URLs refering to the two most recent versions. If you document the concept this way then everyone should understand the semantics.

> I suspect that /docs/ will forever point at the 1.3 docs, and that
> would  be unfortunate. It would be very nice (imho) if we could all
> just say backward compatibility be damned, point /docs/ at the
> 2.current docs, and put in a ErrorDocument 404 for those URLs
> that don't have an equivalent doc in the current documentation.

It depends on your documentation of the URL concept. I understand well that you would _like_ /docs/ to play the role of /docs-stable/ but I can well live with /docs-stable/ and some note about the historical origin of the /docs/ URL. The important thing to me would be to have _any_ "dynamic semantical" URL, while I care less about its actual name, as long as the concept is transparent. Just place a big note on the 1.3 docs start page that you consider this version to be no longer the best one (and add a link to /docs-stable/ there... wouldn't this be a self-explanatory example?). The same would apply to the start page of the 2.0 version once you moved on to 2.2.
And if there is more than one such URL, maybe using /docs-stable/ is even better than /docs/, because you would not confuse people whether /docs/ is equivalent to /docs-stable/ or /docs-latest/ or /docs-dev/ or whatever.

> I don't know what CVS/SVN magic would be necessary to make this happen,

I wouldn't change anything about the CVS structure. The additional semantic URLs can simply be added on the "Alias" level of server configuration.

> but I do know that maintaining 3 versions of the docs is plenty painful
> enough, and I'm not anxious for it to get worse with each rev of the
> code.

I think that's the main issue: How long into the past are you willing to support the docs of old versions? Currently you support Apache 1.3 by still publishing patch versions, therefore updating the docs as well sounds reasonable. (Perhaps the support for 2.0 will be terminated earlier than the support to 1.3, because 2.0 users have less excuse not to upgrade to 2.2 than 1.3 users have?)
You can of course remove the 2.0 docs tree one day, replacing it by some redirection mechanism as to catch broken links, explaining which version they ought to point now (and possibly automatically redirect there in case the structure is still compatible - but this might be dangerous if the visitor expects to read the 2.0 docs and is led to something more modern which his own server doesn't yet support).

Regards, Michael

_____________________________________________________

Diese E-Mail enth�lt vertrauliche Informationen und ist nur f�r den in der E-Mail genannten Adressaten bestimmt. Bitte verst�ndigen Sie den Absender dieser E-Mail unter folgender Rufnummer +49 (0) 69 - 717 00 0, falls Sie diese E-Mail irrt�mlich erhalten haben, und l�schen Sie diese E-Mail. Der Inhalt dieser E-Mail ist nur rechtsverbindlich, wenn er von unserer Seite schriftlich durch Brief oder Telefax best�tigt wird. Die Versendung von E-Mails an uns hat keine fristwahrende Wirkung.