Mailing List Archive: Apache: Docs

On line docs

Index | Next | Previous | View Threaded

tony at pc-tony

Oct 2, 2007, 2:48 PM

Post #1 of 7 (1069 views)
Permalink

On line docs

Good day one and all,

With the threads [1] on dev@ discussing the end of 1.3 support,
gathering some pace, I wanted to re-raise something that really bugs me
just as I know it does other too.

When going to http://httpd.apache.org/docs/mod-foo.html it defaults to
the 1.3 version of the documentation, I would like to see this either
removed, or people are redirected to 2.2 at least. This could be
changed at a later date, as and when the next major release, is er,
released.

We would need to ensure that /docs/mod-foo.html is not directly
referenced anywhere, either in the online docs, or with the src that
ships with each tarball.

We already have a page at /docs/ with links too

/docs/1.3/
/docs/2.0/
/docs/2.2/
/docs/trunk/

Maybe this page could be 'spruced' up a little to make it more
informative, and more likely to lead people in the right direction.

Redirecting to 1.3 by default could be seen to be implying that this is
what 'they' should be reading and/or using, is this really what we want?

I am trying to think of a way to handle the people who would still go to
/docs/mod-foo.html, possibly redirecting them to a "handling/routing
function" where they select the version of HTTPd that they want to see
the documentation for, for that explicit module/page. A simple PHP page
perhaps?

A second method we could use (thanks for reminding me of the obvious
megaspaz) is to use a rewritecond, to check for /docs/(1.3|2.0|2.2|)
and rewrite those without to a landing page, showing how to find the
version of the docs they want.

Alternatively, we could stop forcing a default version of the docs on
people, and stop /docs/mod-foo.html from working altogether

I am not trying to open a huge can of worms here, just merely expressing
an interest.

Thoughts?

Cheers,
Tony

[1] http://marc.info/?l=apache-httpd-dev&m=119135322323186&w=2
http://marc.info/?l=apache-httpd-dev&m=119135717406985&w=2

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

jorge.schrauwen at gmail

Oct 2, 2007, 3:24 PM

Post #2 of 7 (1027 views)
Permalink

Re: On line docs [In reply to]

On 10/2/07, Tony Stevenson <tony [at] pc-tony> wrote:
>
> Good day one and all,
>
> With the threads [1] on dev@ discussing the end of 1.3 support,
> gathering some pace, I wanted to re-raise something that really bugs me
> just as I know it does other too.
>
> When going to http://httpd.apache.org/docs/mod-foo.html it defaults to
> the 1.3 version of the documentation, I would like to see this either
> removed, or people are redirected to 2.2 at least. This could be
> changed at a later date, as and when the next major release, is er,
> released.

Oh yes it defaulting to 1.3 is something I don't like either.

We would need to ensure that /docs/mod-foo.html is not directly
> referenced anywhere, either in the online docs, or with the src that
> ships with each tarball.

+1

We already have a page at /docs/ with links too
>
> /docs/1.3/
> /docs/2.0/
> /docs/2.2/
> /docs/trunk/
>
> Maybe this page could be 'spruced' up a little to make it more
> informative, and more likely to lead people in the right direction.
>
> Redirecting to 1.3 by default could be seen to be implying that this is
> what 'they' should be reading and/or using, is this really what we want?
>
> I am trying to think of a way to handle the people who would still go to
> /docs/mod-foo.html, possibly redirecting them to a "handling/routing
> function" where they select the version of HTTPd that they want to see
> the documentation for, for that explicit module/page. A simple PHP page
> perhaps?
>

Not sure if many things around here are php, I like megaspaz's mod_rewrite
idea better.

A second method we could use (thanks for reminding me of the obvious
> megaspaz) is to use a rewritecond, to check for /docs/(1.3|2.0|2.2|)
> and rewrite those without to a landing page, showing how to find the
> version of the docs they want.

+1

Alternatively, we could stop forcing a default version of the docs on
> people, and stop /docs/mod-foo.html from working altogether

-1
I think this is a bad idea because undoutably a lot of site will be linking
against that uri.
Making it give a 404 or move or gone or whatever seems like a bad idea.

I do like the idea of a landing page where the users selects the correct
version and optionally a text explaining how he can find out which version
he/she is running.

I am not trying to open a huge can of worms here, just merely expressing
> an interest.
>
>
> Thoughts?

Yep and if you are reading this you've read them :)

Cheers,
> Tony
>
>
>
> [1] http://marc.info/?l=apache-httpd-dev&m=119135322323186&w=2
> http://marc.info/?l=apache-httpd-dev&m=119135717406985&w=2
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>
>

Jorge
--
~Jorge

joshua at slive

Oct 2, 2007, 5:14 PM

Post #3 of 7 (1022 views)
Permalink

Re: On line docs [In reply to]

On 10/2/07, Tony Stevenson <tony [at] pc-tony> wrote:
> Good day one and all,
>
> With the threads [1] on dev@ discussing the end of 1.3 support,
> gathering some pace, I wanted to re-raise something that really bugs me
> just as I know it does other too.
>
> When going to http://httpd.apache.org/docs/mod-foo.html it defaults to
> the 1.3 version of the documentation, I would like to see this either
> removed, or people are redirected to 2.2 at least. This could be
> changed at a later date, as and when the next major release, is er,
> released.

Oh man, not this topic again. ;-) You guys should search the archives
a little. This always causes a heated debate.

To clarify, the stuff directly under /docs/ (with no version number)
is not the "default" docs; it is a bunch of legacy urls that redirect
to the canonical location of what once lived there. None of our
content should currently link there, and it should never be used for
anything.

So exactly what problem are you trying to solve? If you just don't
like the idea that stuff under there redirects to an obsolete version,
I say learn to live with it. Because the alternative is to break a ton
of legacy links to the 1.3 docs. (Broken in one of two sense: either
broken 404 because the new docs don't necessarily have all the same
pages; or broken because someone really intended to link to 1.3, not
the most recent version.) I HATE breaking urls.

On the other hand, feal very free to spruce up the /docs/ index page,
and perhaps also update the ssi header include file used in the 1.3
docs. It currently says "Is this the version you want? For more recent
versions, check our documentation index." I believe it could say "You
are reading the documentation for an obsolete version of the server.
For the current version, check our documentation index." And we could
perhaps try to provide direct links to the appropriate place in the
2.2 docs where appropriate.

Joshua.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

jorge.schrauwen at gmail

Oct 3, 2007, 5:40 AM

Post #4 of 7 (1024 views)
Permalink

Re: On line docs [In reply to]

On 10/3/07, Joshua Slive <joshua [at] slive> wrote:
>
> On 10/2/07, Tony Stevenson <tony [at] pc-tony> wrote:
> > Good day one and all,
> >
> > With the threads [1] on dev@ discussing the end of 1.3 support,
> > gathering some pace, I wanted to re-raise something that really bugs me
> > just as I know it does other too.
> >
> > When going to http://httpd.apache.org/docs/mod-foo.html it defaults to
> > the 1.3 version of the documentation, I would like to see this either
> > removed, or people are redirected to 2.2 at least. This could be
> > changed at a later date, as and when the next major release, is er,
> > released.
>
> Oh man, not this topic again. ;-) You guys should search the archives
> a little. This always causes a heated debate.
>
> To clarify, the stuff directly under /docs/ (with no version number)
> is not the "default" docs; it is a bunch of legacy urls that redirect
> to the canonical location of what once lived there. None of our
> content should currently link there, and it should never be used for
> anything.
>
> So exactly what problem are you trying to solve? If you just don't
> like the idea that stuff under there redirects to an obsolete version,
> I say learn to live with it. Because the alternative is to break a ton
> of legacy links to the 1.3 docs. (Broken in one of two sense: either
> broken 404 because the new docs don't necessarily have all the same
> pages; or broken because someone really intended to link to 1.3, not
> the most recent version.) I HATE breaking urls.
>
> On the other hand, feal very free to spruce up the /docs/ index page,
> and perhaps also update the ssi header include file used in the 1.3
> docs. It currently says "Is this the version you want? For more recent
> versions, check our documentation index." I believe it could say "You
> are reading the documentation for an obsolete version of the server.
> For the current version, check our documentation index." And we could
> perhaps try to provide direct links to the appropriate place in the
> 2.2 docs where appropriate.
>
> Joshua.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>
>
I see your concern with breaking links from other sides but what about
something like this:

every request that has a non empty referal field goes to 1.3 so links don't
break.
the onces with a blank one to a page witch a chose between 1.3 , 2.0, 2.2,
trunk?

Just some ideas

--
~Jorge

nd at perlig

Oct 3, 2007, 6:13 AM

Post #5 of 7 (1027 views)
Permalink

Re: On line docs [In reply to]

* Jorge Schrauwen wrote:

> I see your concern with breaking links from other sides but what about
> something like this:
>
> every request that has a non empty referal field goes to 1.3 so links
> don't break.
> the onces with a blank one to a page witch a chose between 1.3 , 2.0,
> 2.2, trunk?

This pops the question again, what problem are we trying to solve here? And
what problem would your suggestion solve anyway? ;-) Direct type-ins? How
many people do that actually?
Personally I either use google and find the direct link or click through the
navigation. Most people I know even start with www.apache.org and click
through.

nd
--
s s^saaaaaoaaaoaaaaooooaaoaaaomaaaa a alataa aaoat a a
a maoaa a laoata a oia a o a m a o alaoooat aaool aaoaa
matooololaaatoto aaa o a o ms;s;\s;s;g;y;s;:;s;y#mailto: #
\51/\134\137| http://www.perlig.de #;print;# > nd [at] perlig

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

erik at codefaktor

Oct 4, 2007, 6:31 AM

Post #6 of 7 (994 views)
Permalink

Re: On line docs [In reply to]

On 03.10.2007, at 02:14, Joshua Slive wrote:

> On 10/2/07, Tony Stevenson <tony [at] pc-tony> wrote:
>> ...
>> When going to http://httpd.apache.org/docs/mod-foo.html it
>> defaults to
>> the 1.3 version of the documentation, I would like to see this either
>> removed, or people are redirected to 2.2 at least. This could be
>> changed at a later date, as and when the next major release, is er,
>> released.
>
> ...
> To clarify, the stuff directly under /docs/ (with no version number)
> is not the "default" docs; it is a bunch of legacy urls that redirect
> to the canonical location of what once lived there. None of our
> content should currently link there, and it should never be used for
> anything.

Right, and a grep on the logs for September shows that only 0.99% [1]
of all requests to /docs/* are affected, so really negligible.

> ...
> On the other hand, feal very free to spruce up the /docs/ index page,
> and perhaps also update the ssi header include file used in the 1.3
> docs. It currently says "Is this the version you want? For more recent
> versions, check our documentation index." I believe it could say "You
> are reading the documentation for an obsolete version of the server.
> For the current version, check our documentation index."
> ...

Yep, I think this is the best we can/should do.

Just my 2c...

Cheers,
Erik

[1] 108664 out of a total of 10874293 requests

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

rbowen at rcbowen

Oct 5, 2007, 10:22 AM

Post #7 of 7 (996 views)
Permalink

Re: On line docs [In reply to]

On Oct 4, 2007, at 09:31, Erik Abele wrote:
>>
>> To clarify, the stuff directly under /docs/ (with no version number)
>> is not the "default" docs; it is a bunch of legacy urls that redirect
>> to the canonical location of what once lived there. None of our
>> content should currently link there, and it should never be used for
>> anything.
>
> Right, and a grep on the logs for September shows that only 0.99%
> [1] of all requests to /docs/* are affected, so really negligible.

That is a surprising statistic, and is quite different from my gut
feeling about how it would be. Thanks for providing actual data. It
certainly puts things on a more useful footing. I'd be interested to
see the trend over time, but I'm reasonably sure we'd see this number
shrink.

>
>> ...
>> On the other hand, feal very free to spruce up the /docs/ index page,
>> and perhaps also update the ssi header include file used in the 1.3
>> docs. It currently says "Is this the version you want? For more
>> recent
>> versions, check our documentation index." I believe it could say "You
>> are reading the documentation for an obsolete version of the server.
>> For the current version, check our documentation index."
>> ...
>
> Yep, I think this is the best we can/should do.

+1

I know, I'm one of the ones who in the first place wanted /docs to go
to /docs/current but I find myself in agreement with Joshua's
explanation of how things are and should be.

--
If you miss this moment
You miss your life

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads