httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Slive <jos...@slive.ca>
Subject Re: prototype FAQ
Date Fri, 23 Feb 2001 17:55:34 GMT

On Fri, 23 Feb 2001, Rodent of Unusual Size wrote:

> Joshua Slive wrote:
> >
> > 4. Changed the format of the Q&A to <h3>s rather than a big
> > <ol>.  There is no longer any numbering in the FAQ.
>
> -1.  I often refer people to specific questions by number.
> Hard-code them into the <h3> if you like, but use an <ol>
> for the index.  And continue to have a link for a single massive
> all-inclusive page -- otherwise printing is a major PITA.

Re the numbering.  I did this for a specific reason: If we number the FAQ
and people start referring to the numbers, then it becomes very difficult
in the future to do any sort of reorganization.  It would be much nicer if
we had the flexibility to say "This is the most important question, so it
should be listed first."  All questions have URLs, so the numbering
shouldn't really be necessary.  On the other hand, I understand the desire
to have them, and I am not permanently wedded to the numberless concept.

I'll deal with the "one big page" issue below.

>
> > I believe we should just give up on the idea of having a
> > plain-text FAQ to post to usenet.  That created a bunch of
> > complication and nobody every actually did it anyway.
>
> -1.  Just because it has not been done does *not* mean we
> should make it more difficult to do than it already is.
> Besides, it is still on my to-do list.

People have been saying that from at least the time I started watching the
Apache project, and probably long before that.  It has never happened.  In
any case, I don't think it is a very useful thing to do.  We have passed
the point on usenet where posting 5,000 line FAQs does anyone any good.  A
simple periodic post with a URL accomplishes the same thing with much less
pain all around.

What are we losing with this?  Well, as I see it, one of the primary
reasons that the 1.3 FAQ is unmanageable is this requirement.  I would
guess that a fair number of the FAQs that are asked on usenet get asked
not because people haven't bothered to look at the FAQ, but rather because
the FAQ is so unwieldy that they gave up before they found the answer.

If we want something that is clearly layed out, easy to navigate,
heirerarchical, and easy to maintain, then what I presented is the way to
go.  If you want something that can easily be posted to usenet and printed
as a single page, then I will just go back to the old design and remove
most of the questions.  I'm certainly not going to create some new SSI
monstrosity.  However, we will be back in the same unmanageable situation
in a year or so.

Please reconsider this veto Ken.

>
> I would actually consider nuking the entire first 'background'
> section.  I do not recall ever actually being asked any of
> the questions listed there, in email, in person, or in the
> newsgroups.  (Well, except for the 'where do I get' one, which
> has always been due to blindness when looking at the main site
> or the download area.)

I'm happy to nuke the first section.  Perhaps some of that stuff should be
moved to httpd-site.

Joshua.


Mime
View raw message