httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David Reid" <dr...@jetnet.co.uk>
Subject Re: prototype FAQ
Date Sun, 25 Feb 2001 12:07:11 GMT
> On Sat, 24 Feb 2001, David Reid wrote:
> >
> > If we can do all this then I'll be +1 :), but presently I'm -0.5 on the
> > sample you created.

I do have a comment about your posting.  The subject line on the email that
led me to the sample was "prototype FAQ".  It wasn't "hey, see what you
think of this" or "Feedback on possible FAQ layout" or any such.  I realise
it's semantics to a degree but the subject line did seem like a fait
accompli and that was why I jumped in with a reply when i did, rather than
wait until I'd had some sleep.

> I assume "you" refers to "me".

Nope, just who ever did it, whether a single person or a group.  Bit like
the "royal we" can refer to any number of people :)  Call it a strangeness
of our beloved language this side of the water... :)

>
> It's good to have more voices in the discussion, but it would be nice to
> have a little more explanation.  You commented on Ken's goals, but didn't
> make any comments on the actual prototype, or how it fulfills these goals,
> other than to say you are "-0.5".  That's a judgement, but not a
> explanation. The goals themselves are fine (except for #2 which I still
> don't understand; nobody has given me actual concrete reasons why it is
> important... Ken?).

Yeah, sorry about that but the thing uppermost on my mind was sleep when I
posted the reply :)  Anyway, more explanation...

The FAQ should be split.  How often do you go to a web site, get confronmted
by a 200Kb FAQ that doesn't appear to have much organisation, spend 20
minutes looking at questions and answers that don't help and then go
elsewhere.  We're all agreed that the FAQ is an invaluable resource, that it
should be peoples first stop when they have problems and that done correctly
it'll be a huge asset for the project.  Nuff said really.  now we just need
to decide what all that means in real terms :)

Let's not even look at the old versions.  This is something we need to get
right.  We're not starting from anywhere, and we don't really have to follow
a certain path, so let's think laterally and get something we want.

Ideally I'd like to see an FAQ that has

- a nice easy to follow structure
- relevant sections that each have relevant questions/answers
- some form of numbering/referencing such that we can publish an index type
page to allow specific URL's to be given out

What I didn't like about the one I looked at (the URL you sent so I guess
the one you did??) was that the sections didn't seem to be especially
relevant or were too big to be relevant.  For instance,

Building Apache

OK, how many platforms do we have?  How many variations in compilers etc
within platforms?  This is a huge topic and one that will provide a lot of
answers for people.  OK, so the next page could have it subdivided, but I'd
rather see this split here, e.g.

Building Apache
    Unix
        Requirements
        Configuring
        Building
        Platform Specific Issues
    Windows
        Requirements
        Building
    OS/2
    ...
    Adding PHP
    Adding mod_perl
    Adding mod_snake



This seems to allow people to go straight to the page they're looking for in
less time.  Each page is smaller and hence requires less effort to look at
and digest.

I realise that this all involves more work to write and so on, but again I
think we should seriously not even think about moving on unless we start
using some form of seperation between data and style.  If that's using an
XML template or some other system I don't really mind, but if we don't do it
now we'll be kicking ourselves before too long.  I still think that the FAQ
will throw up more issues than any of the other projects and so is a useful
project to get our teeth into doing it.  I may be wrong, but I think there
are a few systems out there already for doing this sort of thing for FAQ's?
Maybe someone (I'd like to offer but I don't have anywhere near enough time)
should trawl and see what's available, suitable and provide some feedback
here.  Ryan did that with the doc generators for APR and he did an excellent
job in providing us all with information, examples and so on.

Anyway, hope that helps and makes sense...


>
> In any case, it looks like people prefer to stick to the old FAQ.

Nope.  Don't think that's what people are saying at all. :(

david



Mime
View raw message