You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Rich Bowen <rb...@rcbowen.com> on 2004/09/10 22:15:09 UTC
Documentation URLs
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
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.
It seems that each time we discuss this, the discussion doesn't reach
any real conclusions. Or at least, I haven't seen any yet. If I missed
something, feel free to point me at the archives. I just kinda feel that
we need to figure out something in advance, rather than being reactive
when the time comes.
How about ...
/docs-stable/ -- Current released version (2.0 now)
/docs-dev/ -- Current development version (2.1 now)j
And, maybe
/docs-legacy/ -- Recently supplanted version.
Maybe. But I'm not sure if/why we need that.
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. Then /docs-1.3/ could point
to the 1.3 docs for all time, and the rest of the documentation can move
on.
I don't know what CVS/SVN magic would be necessary to make this happen,
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.
Thoughts?
- --
Unix - Twice the power, and none of the subtlety
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)
iD8DBQFBQgtUXP03+sx4yJMRAkOIAKCPFdo/6rmZ1yJj1GQUKceSG/BoZwCgwJG/
xoyhweDfKn1cZ88PrexGPgI=
=hWhk
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Erik Abele <er...@codefaktor.de>.
On 25.09.2004, at 11:07, Astrid Keßler wrote:
>> I'd like to see more of a concrete statement of what problem we are
>> trying
>> to solve. If it is just a question of ugly urls, I don't think it is
>> worth solving.
>
> Ough. Well, I'll try to make it more clear:
> ...
> We better offer an overview page at /docs and, for backwards
> compatibility, link to the new URI generated from the request line.
> We should have done the move much earlier, but have not. So we should
> do it now. The longer we wait, the harder will it be.
+1 to an overview page at /docs. I also like Will's suggestion to use a
more verbose page for the then lost URIs under /docs/* instead of just
simply auto-redirecting to the new location under /docs-1.3/. This
should also help Google, I think...
Reaching the 1.3 docs when going to /docs bugged me for quite some time
now but to be honest, I didn't dare to ask for opinions ;)
Cheers,
Erik
Re: Documentation URLs
Posted by Astrid Keßler <ke...@kess-net.de>.
> I'd like to see more of a concrete statement of what problem we are trying
> to solve. If it is just a question of ugly urls, I don't think it is
> worth solving.
Ough. Well, I'll try to make it more clear:
Nothing is ugly. /docs is - not in the past, but now and in future -
simply wrong. People are thinking simple. Most of them expect to find
the documentation of the current stable release when going to /docs. Or
to find an overview about the available versions. They do not expect to
find an old (some day really outdated) version.
People are trying simple URLs or they are searching with simple words.
In most cases they are coming to /docs, expecting the documentation of
the current stable version, which is 2.0 at the moment and will be 2.2,
2.4 and so on in future. But what do they find? They find 1.3.
So what do they think?
They may realize, it's an older version and search for the new one.
So they have additional effort, finding the corresponding documentation
they want. We are able to minimize this effort by offering an overview
about available versions at /docs.
They may realize, it's an older version and think "Stupid Apache
developers. Their docs are completely outdated. If their docs reflect
their coding, I better do not use it."
Ok, this is exaggerated. But some people may get such a feeling.
They may realize, /docs is containing version 1.3 and will think, this
is the recommended version. They may feel, that we do not trust our own
newer Versions.
Or they do not realize, it's an older version and try to configure
their sever by using the wrong documentation. After some time they will
grumble, that the docs are wrong.
At all, I think, we do not win much by keeping /docs pointing to 1.3.
We better offer an overview page at /docs and, for backwards
compatibility, link to the new URI generated from the request line.
We should have done the move much earlier, but have not. So we should
do it now. The longer we wait, the harder will it be.
Kess
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Joshua Slive <jo...@slive.ca>.
On Fri, 24 Sep 2004, Rich Bowen wrote:
> The problem is that we are stating that people should use Apache 2.0,
> but our website has the 1.3 docs as the default documentation on the
> website when you go to /docs
OK. But the 1.3 docs are not favoured in any way except by not having the
version number in the URL. I'm not sure I see this as causing great
confusion.
I won't stand in the way of someone correcting this. I'm just pointing
out that there may be some cost.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Rich Bowen <rb...@rcbowen.com>.
On Fri, 24 Sep 2004, Joshua Slive wrote:
>
> On Fri, 24 Sep 2004, Astrid Keßler wrote:
> >> But note this could have adverse effects for things like google searches.
> >> Google would probably see the redirect and wipe out all the good karma we
> >> get from links to those pages.
> >
> > It is just a (imho short) question of time Google (and other search
> > engines) will renew their index and rebuild the karma for the new URIs.
> > Not to change the meaning of /docs will do us much more pain. I don't
> > want to hear "hey, forget apache. their docs are really outdated". And
> > this is, what may (will?) come some day, if we keep our current URI
> > structure.
>
> I don't believe this is entirely true. The karma comes from the links,
> and my observation is that links rarely get updated when content moves.
>
> And there are probably other consequences of changing URLs.
>
> I'd like to see more of a concrete statement of what problem we are trying
> to solve. If it is just a question of ugly urls, I don't think it is
> worth solving.
The problem is that we are stating that people should use Apache 2.0,
but our website has the 1.3 docs as the default documentation on the
website when you go to /docs
I don't think that 'ugly urls' ever really occurred to me as a problem.
I would simply like /docs to point to the documentation for the
recommended version of our software.
--
Pilgrim, how you journey on the road you chose
To find out where the winds die and where the stories go
--Pilgrim (Enya - A Day Without Rain)
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Joshua Slive <jo...@slive.ca>.
On Fri, 24 Sep 2004, Astrid Ke�ler wrote:
>> But note this could have adverse effects for things like google searches.
>> Google would probably see the redirect and wipe out all the good karma we
>> get from links to those pages.
>
> It is just a (imho short) question of time Google (and other search
> engines) will renew their index and rebuild the karma for the new URIs.
> Not to change the meaning of /docs will do us much more pain. I don't
> want to hear "hey, forget apache. their docs are really outdated". And
> this is, what may (will?) come some day, if we keep our current URI
> structure.
I don't believe this is entirely true. The karma comes from the links,
and my observation is that links rarely get updated when content moves.
And there are probably other consequences of changing URLs.
I'd like to see more of a concrete statement of what problem we are trying
to solve. If it is just a question of ugly urls, I don't think it is
worth solving.
Joshua.
Re: Documentation URLs
Posted by Rich Bowen <rb...@rcbowen.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On Mon, 27 Sep 2004 Michael.Schroepl@telekurs.de wrote:
> > It is just a (imho short) question of time Google (and other search
> > engines) will renew their index and rebuild the karma for the new URIs.
>
> I am not really sure about this.
>
> I believe the "karma" of Google is the results of popular pages linking
> to certain URLs, thus assing the popularity of these pages to the rank
> of the link target.
> So if the link target is no longer there then it might vanish from the
> Google database sooner or later (because Google traverses known sites
> now and then and might recognize the redirection, thus replacing the
> known URL by the new URL).
> Therefore I believe changing URLs would actually make them lose their
> rank in Google until other pages update their content as to link to the
> new URLs, then again adding their popularity to these pages.
Well, you know, we know someone at Google now, so just maybe we can get
some advice direct from the horse's mouth on this issue. Is Greg on this
list?
> Just a question out of curiosity: Did the Apache site ever provide
> documentation for versions 1.2 and 1.3 in parallel? If so, how was
> the problem taken care of back then?
As I remember it, /docs was just /docs. Things changed between 1.2 and
1.3, but the /docs was just updated to reflect the new reality, with the
"Compatibility" part of each directive updated appropriately. So, no,
there was not a 1.2 and 1.3 docs tree.
Changes between 1.3 and 2.0, of course, are much more significant.
- --
Pilgrim, how you journey on the road you chose
To find out where the winds die and where the stories go
--Pilgrim (Enya - A Day Without Rain)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)
iD8DBQFBWp5ZXP03+sx4yJMRAsU8AKCUQnQR2T3TMFsftImVMyZq8IrnXwCeIE3d
2ebbGqW3QegCLsGDGrBG9os=
=tnC9
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Mi...@telekurs.de.
> It is just a (imho short) question of time Google (and other search
> engines) will renew their index and rebuild the karma for the new URIs.
I am not really sure about this.
I believe the "karma" of Google is the results of popular pages linking
to certain URLs, thus assing the popularity of these pages to the rank
of the link target.
So if the link target is no longer there then it might vanish from the
Google database sooner or later (because Google traverses known sites
now and then and might recognize the redirection, thus replacing the
known URL by the new URL).
Therefore I believe changing URLs would actually make them lose their
rank in Google until other pages update their content as to link to the
new URLs, then again adding their popularity to these pages.
> Not to change the meaning of /docs will do us much more pain. I don't
> want to hear "hey, forget apache. their docs are really outdated".
> And this is, what may (will?) come some day, if we keep our current URI
> structure.
If that's the problem then I repeat my suggestion as to put a _huge_
link on the Apache 1.3 docs start page (which is where the visitors
will start if they assume the current docs to reside here) pointing
to the current version (whichever this may be) and reading "Current
Version: 2.0" or something like that.
(This link should probably be auto-generated so that updating it
won't be forgotten in case of a change of the latest release.)
Just a question out of curiosity: Did the Apache site ever provide
documentation for versions 1.2 and 1.3 in parallel? If so, how was
the problem taken care of back then?
>> ... Another option would also be, add a checkbox for a doc cookie,
>> 'Always choose this version', which would bypass this page and
>> always redirect that browser to the right section.
>
> Uh -1.
> That would be much confusing.
>
> Vary: Cookie?
> Proxies?
I believe that "Vary: Cookie" (added via configuration for this page
alone) should solve the problem for modern proxies (Squid 2.5+).
One alternative would be to deny proxy caching for this special page
(which isn't that big after all, although it might have many hits).
Remember that sending compressed content (mod_deflate) poses the same
problem for caching proxies (which are required to understand the
negotional nature of a page sending "Vary:").
Is this the reason for not sending compressed content at all?
(Currently the Apache docs appear to be served uncompressed.)
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.
Re: Documentation URLs
Posted by Astrid Keßler <ke...@kess-net.de>.
Joshua wrote:
> On Wed, 22 Sep 2004, Astrid Keßler wrote:
>>> What primarily bugs me is two things:
>>> 1) That /docs/ is the 1.3 documentation, while we're trying to present a
>>> message that 2.0 is the Right Thing To Use.
>>
>>> If the canonical documentation URL "/docs/" points to 1.3, then
>>> *obviously* 1.3 must be the recommended version.
>>
>> What about moving docs to docs-1.3 and adding an info page to docs? Such
>> a page could inform the user about the move, the existing versions and
>> maybe a (dynamicly created) link to the corresponding 1.3 manual page,
>> the user originally requested. This won't break anything but offers a
>> central entry point to _all_ manual versions.
> This is fine if people want. The info page could be restricted to just
> the root, with other requests getting auto-redirected.
> But note this could have adverse effects for things like google searches.
> Google would probably see the redirect and wipe out all the good karma we
> get from links to those pages.
It is just a (imho short) question of time Google (and other search
engines) will renew their index and rebuild the karma for the new URIs.
Not to change the meaning of /docs will do us much more pain. I don't
want to hear "hey, forget apache. their docs are really outdated". And
this is, what may (will?) come some day, if we keep our current URI
structure.
Kess
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Mads Toftum <ma...@toftum.dk>.
On Fri, Sep 24, 2004 at 01:09:09PM -0500, William A. Rowe, Jr. wrote:
> What about an auto-script for /docs/* that says (lets use the
> example of /docs/mod/directives.html)
>
> The httpd docs project team has split the information for your
> convenience between the following versions, please indicate
> which version you are using;
>
> Apache httpd 1.3 /docs-1.3/mod/directives.html
> Apache httpd 2.0 /docs-2.0/mod/directives.html
> Apache httpd 2.1-dev /docs-2.2/mod/directives.html
>
+1 - I had pretty much the same idea, but never got around to sending it :)
> You can update your bookmarks according.
>
> ... Another option would also be, add a checkbox for a doc cookie,
> 'Always choose this version', which would bypass this page and
> always redirect that browser to the right section.
>
A nice added feature - +1 on that too.
vh
Mads Toftum
--
`Darn it, who spiked my coffee with water?!' - lwall
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by André Malo <nd...@perlig.de>.
* "William A. Rowe, Jr." <wr...@rowe-clan.net> wrote:
> ... Another option would also be, add a checkbox for a doc cookie,
> 'Always choose this version', which would bypass this page and
> always redirect that browser to the right section.
Uh -1.
That would be much confusing.
Vary: Cookie?
Proxies?
nd
--
$_=q?tvc!uif)%*|#Bopuifs!A`#~tvc!Xibu)%*|qsjou#Kvtu!A`#~tvc!KBQI!)*|~
tvc!ifmm)%*|#Qfsm!A`#~tvc!jt)%*|(Ibdlfs(~ # What the hell is JAPH? ;
@_=split/\s\s+#/;$_=(join''=>map{chr(ord( # André Malo ;
$_)-1)}split//=>$_[0]).$_[1];s s.*s$_see; # http://www.perlig.de/ ;
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by "William A. Rowe, Jr." <wr...@rowe-clan.net>.
What about an auto-script for /docs/* that says (lets use the
example of /docs/mod/directives.html)
The httpd docs project team has split the information for your
convenience between the following versions, please indicate
which version you are using;
Apache httpd 1.3 /docs-1.3/mod/directives.html
Apache httpd 2.0 /docs-2.0/mod/directives.html
Apache httpd 2.1-dev /docs-2.2/mod/directives.html
You can update your bookmarks according.
... Another option would also be, add a checkbox for a doc cookie,
'Always choose this version', which would bypass this page and
always redirect that browser to the right section.
At 12:19 PM 9/24/2004, you wrote:
>On Wed, 22 Sep 2004, Astrid Keßler wrote:
>
>>>What primarily bugs me is two things:
>>>1) That /docs/ is the 1.3 documentation, while we're trying to present a
>>>message that 2.0 is the Right Thing To Use.
>>
>>>If the canonical documentation URL "/docs/" points to 1.3, then
>>>*obviously* 1.3 must be the recommended version.
>>
>>What about moving docs to docs-1.3 and adding an info page to docs? Such
>>a page could inform the user about the move, the existing versions and
>>maybe a (dynamicly created) link to the corresponding 1.3 manual page,
>>the user originally requested. This won't break anything but offers a
>>central entry point to _all_ manual versions.
>
>This is fine if people want. The info page could be restricted to just the root, with other requests getting auto-redirected.
>
>But note this could have adverse effects for things like google searches. Google would probably see the redirect and wipe out all the good karma we get from links to those pages.
>
>Joshua.
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
>For additional commands, e-mail: docs-help@httpd.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Paul Querna <ch...@force-elite.com>.
On Fri, 2004-09-24 at 13:19 -0400, Joshua Slive wrote:
> But note this could have adverse effects for things like google searches.
> Google would probably see the redirect and wipe out all the good karma we
> get from links to those pages.
Google will find it again with time.
I have faith in Google.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Joshua Slive <jo...@slive.ca>.
On Wed, 22 Sep 2004, Astrid Ke�ler wrote:
>> What primarily bugs me is two things:
>> 1) That /docs/ is the 1.3 documentation, while we're trying to present a
>> message that 2.0 is the Right Thing To Use.
>
>> If the canonical documentation URL "/docs/" points to 1.3, then
>> *obviously* 1.3 must be the recommended version.
>
> What about moving docs to docs-1.3 and adding an info page to docs? Such
> a page could inform the user about the move, the existing versions and
> maybe a (dynamicly created) link to the corresponding 1.3 manual page,
> the user originally requested. This won't break anything but offers a
> central entry point to _all_ manual versions.
This is fine if people want. The info page could be restricted to just
the root, with other requests getting auto-redirected.
But note this could have adverse effects for things like google searches.
Google would probably see the redirect and wipe out all the good karma we
get from links to those pages.
Joshua.
Re: Documentation URLs
Posted by Astrid Keßler <ke...@kess-net.de>.
> What primarily bugs me is two things:
> 1) That /docs/ is the 1.3 documentation, while we're trying to present a
> message that 2.0 is the Right Thing To Use.
> If the canonical documentation URL "/docs/" points to 1.3, then
> *obviously* 1.3 must be the recommended version.
What about moving docs to docs-1.3 and adding an info page to docs? Such
a page could inform the user about the move, the existing versions and
maybe a (dynamicly created) link to the corresponding 1.3 manual page,
the user originally requested. This won't break anything but offers a
central entry point to _all_ manual versions.
> 2) That we'll end up with a progressively larger number of documentation
> trees that will have to be maintained.
> It's already a pain to patch the 2.0 and 2.1 docs. What will it be like
> by version 2.24?
It's not only a docs issue. It is also a general development problem.
Our developers are also maintaining three versions. Eventually we will
have to stop maintanance of older httpd versions. At this point we will
also stop maintenance of the corresponding manual.
> That's the sense in it. At least from my perspective. Having /docs/
> point to the current (2.0) docs, and having ErrorDocument 404's to
> handle URLs that are no longer valid in the 2.0 docs, seems to
> completely handle the "breaks links" issue.
I don't think so. As suggested above I would prefer docs to show some
information and list all available documentations, not only the current
stable version or any other single version.
> It seems
> to me, however, that linking /docs/ to the 1.3 docs for all time
> henceforth is not the right decision.
+1
Kess
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Rich Bowen <rb...@rcbowen.com>.
On Fri, 10 Sep 2004, [ISO-8859-15] André Malo wrote:
> * Rich Bowen <rb...@rcbowen.com> wrote:
>
> > -----BEGIN PGP SIGNED MESSAGE-----
> > Hash: SHA1
> >
> > 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.
> >
> > It seems that each time we discuss this, the discussion doesn't reach
> > any real conclusions. Or at least, I haven't seen any yet. If I missed
> > something, feel free to point me at the archives. I just kinda feel that
> > we need to figure out something in advance, rather than being reactive
> > when the time comes.
>
> This was voted some time ago:
> http://cvs.apache.org/viewcvs.cgi/httpd-docs-2.0/STATUS?r1=1.71&r2=1.72&diff_format=h
>
> (which doesn't mean, of course, that it could not be discussed further ;)
>
> > How about ...
> >
> > /docs-stable/ -- Current released version (2.0 now)
> > /docs-dev/ -- Current development version (2.1 now)j
> [...]
>
> I think, stable URLs (with version numbers) are better here, because there are
> many references out there, which would break otherwise.
>
> A compromise could be to add such URLs as placeholders (i.e. redirects) to
> the appropriate docs directory, but I don't see much sense in this.
What primarily bugs me is two things:
1) That /docs/ is the 1.3 documentation, while we're trying to present a
message that 2.0 is the Right Thing To Use.
If the canonical documentation URL "/docs/" points to 1.3, then
*obviously* 1.3 must be the recommended version.
2) That we'll end up with a progressively larger number of documentation
trees that will have to be maintained.
It's already a pain to patch the 2.0 and 2.1 docs. What will it be like
by version 2.24?
That's the sense in it. At least from my perspective. Having /docs/
point to the current (2.0) docs, and having ErrorDocument 404's to
handle URLs that are no longer valid in the 2.0 docs, seems to
completely handle the "breaks links" issue.
Anyways, I'm content to drop it if that's really the consensus. It seems
to me, however, that linking /docs/ to the 1.3 docs for all time
henceforth is not the right decision.
--
My girl came to the study and said Help me;
I told her I had a time problem which meant:
I would die for you but I don't have ten minutes.
Time Problem -- Brenda Hillman
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by André Malo <nd...@perlig.de>.
* Rich Bowen <rb...@rcbowen.com> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> 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.
>
> It seems that each time we discuss this, the discussion doesn't reach
> any real conclusions. Or at least, I haven't seen any yet. If I missed
> something, feel free to point me at the archives. I just kinda feel that
> we need to figure out something in advance, rather than being reactive
> when the time comes.
This was voted some time ago:
http://cvs.apache.org/viewcvs.cgi/httpd-docs-2.0/STATUS?r1=1.71&r2=1.72&diff_format=h
(which doesn't mean, of course, that it could not be discussed further ;)
> How about ...
>
> /docs-stable/ -- Current released version (2.0 now)
> /docs-dev/ -- Current development version (2.1 now)j
[...]
I think, stable URLs (with version numbers) are better here, because there are
many references out there, which would break otherwise.
A compromise could be to add such URLs as placeholders (i.e. redirects) to
the appropriate docs directory, but I don't see much sense in this.
nd
--
"Die Untergeschosse der Sempergalerie bleiben währenddessen aus
statistischen Gründen geflutet." -- Spiegel Online
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Documentation URLs
Posted by Mi...@telekurs.de.
> 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.