httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject Re: Documentation URLs
Date Mon, 20 Sep 2004 09:05:24 GMT
> 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 

> 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 

> 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.

View raw message