Mailing List Archive

Please put me off your mailing list.

----- Original Message -----
From: Raymond S Brand <rsbrand@gate.net>
To: <apache-docs@apache.org>
Sent: Wednesday, August 23, 2000 9:38 AM
Subject: Re: [PATCH] Second try: External Apache tutorials and
mod/index.htmlreorg


> OK, some feedback.
>
> The patch to htdocs/manual/mod/index.html, although useful in its own
right,
> eliminates a useful index of modules sorted by module name.
>
> I recommend not accepting that patch as is.
>
>
> Raymond S Brand
>
>
> Joshua Slive wrote:
> >
> > Okay, I'm going to try this one again too.
> >
> > I see at least a couple possible reasons why my doc patches are being
> > ignored:
> >
> > 1. The people who have commit access don't like them, or think that they
> > are not very important.
> > 2. Nobody with commit access is reading the docs list, or has time
> > to deal with submitted patches.
> >
> > In any case, the exercise seems rather pointless if patches get no
> > feedback at all. I'm not trying to be snotty. I'm just trying to see
if
> > I am wasting my time contributing here. Please let me know.
> >
> > --
> > Joshua Slive
> > slive@finance.commerce.ubc.ca
> > http://finance.commerce.ubc.ca/~slive/
> > Phone: (604) 822-1871
> >
> > ---------- Forwarded message ----------
> > Date: Sat, 19 Aug 2000 15:09:13 -0700 (PDT)
> > From: Joshua Slive <slive@finance.commerce.ubc.ca>
> > Reply-To: apache-docs@apache.org
> > To: apache-docs@apache.org
> > Subject: [PATCH] External Apache tutorials
> >
> > I am submitting a new file for the docs which consists of links to
(mostly
> > external) tutorials. This is meant to help alleviate the steep learning
> > curve and lack of task-oriented material in the current apache docs by
> > leveraging some of the great material that is out there on the web, and
> > putting it in an easily accessible place for newcomers.
> >
> > There are a few concerns with using external linked material:
> > 1. We need to be careful to check the accuracy of the docs.
> > 2. Some of these links will obviously grow stale over time,
> > so some maintenance will be needed.
> > 3. Some sites may not like being "deep-linked" in this way. (No
permission
> > was requested.)
> >
> > Overall, I think the advantages outweigh these concerns.
> >
> > Attached is a draft document which can be dropped into
htdocs/manual/misc
> > and a patch to htdocs/manual/index.html to reference it.
> >
> > --
> > Joshua Slive
> > slive@finance.commerce.ubc.ca
> > http://finance.commerce.ubc.ca/~slive/
> > Phone: (604) 822-1871
> >
>
--------------------------------------------------------------------------
----------------------------------------------------------------------------
--------------------------------------------------
> > Name: index-html-diff.txt
> > index-html-diff.txt Type: Plain Text (TEXT/PLAIN)
> > Encoding: BASE64
> >
> > Name: tutorials.html
> > tutorials.html Type: Hypertext Markup Language (TEXT/HTML)
> > Encoding: BASE64
> >
> > Name: index-html-diff.txt
> > index-html-diff.txt Type: Plain Text (TEXT/plain)
> > Encoding: BASE64
>

On Wed, 23 Aug 2000, Raymond S Brand wrote:

> OK, some feedback.
>
> The patch to htdocs/manual/mod/index.html, although useful in its own right,
> eliminates a useful index of modules sorted by module name.
>
> I recommend not accepting that patch as is.
>

That is reasonable. As I stated in my original email for this patch, I
did consider this and my opinion is that this patch shouldn't really slow
down somebody looking for a specific module (by name) by more that a
couple seconds. (Worst case scenario: hit the alt/ctrl-f in netscape and
type your module name.) However, if others disagree, I would still
suggest making this version the default "modules" page because it is in
the structure that is most useful for a first-time user of the docs. The
alphabetic index could then be linked to this page just as the alphabetic
list of directives is. The "expert" users that would be looking for the
alphabetic index would be expert enough to be able to make the extra click
to find it.

--
Joshua Slive
slive@finance.commerce.ubc.ca
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871

Rob Stewart wrote:
>
> Please put me off your mailing list.

You can remove yourself from it by sending an empty
message to apache-docs-unsubscribe@apache.org.
--
#ken P-)}

Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>

On Wed, 23 Aug 2000, Joshua Slive wrote:

> > OK, some feedback.
> >
> > The patch to htdocs/manual/mod/index.html, although useful in its own right,
> > eliminates a useful index of modules sorted by module name.
> >
> > I recommend not accepting that patch as is.

I think I disagree.

For people not knowing what they are doing the patch will be a big
help in educating them. For people knowing what they are doing it
won't be hard to find the module if the blocks are ordered after
request stage.


- ask

--
ask bjoern hansen - <http://www.netcetera.dk/~ask/>
more than 70M impressions per day, <http://valueclick.com>

Who should the docs be optimal for? The "first time user" or the "regular user"?
I do not believe that the answer should be for the "first time user"; after all,
they probably want/need a tutorial, not the reference manual.

Yes, with the, currently, small number of modules, it's easy enough to just look
through the list to find the module you need but what happens when the number of
modules is not so small. Don't assume that all browsers have reasonable search
facilities.

If this index is going to go into the docs, then I suggest that it and the existing
alphabetical module list both have links from the "top" index page. And to be
complete, you should also create another directive index that categorizes the
individual directives like you did the modules, and link the two directive
indexes off the "top" index page.

Raymond S Brand


My suggestion is to have
Joshua Slive wrote:
>
> On Wed, 23 Aug 2000, Raymond S Brand wrote:
>
> > OK, some feedback.
> >
> > The patch to htdocs/manual/mod/index.html, although useful in its own right,
> > eliminates a useful index of modules sorted by module name.
> >
> > I recommend not accepting that patch as is.
> >
>
> That is reasonable. As I stated in my original email for this patch, I
> did consider this and my opinion is that this patch shouldn't really slow
> down somebody looking for a specific module (by name) by more that a
> couple seconds. (Worst case scenario: hit the alt/ctrl-f in netscape and
> type your module name.) However, if others disagree, I would still
> suggest making this version the default "modules" page because it is in
> the structure that is most useful for a first-time user of the docs. The
> alphabetic index could then be linked to this page just as the alphabetic
> list of directives is. The "expert" users that would be looking for the
> alphabetic index would be expert enough to be able to make the extra click
> to find it.
>
> --
> Joshua Slive
> slive@finance.commerce.ubc.ca
> http://finance.commerce.ubc.ca/~slive/
> Phone: (604) 822-1871

On Wed, 23 Aug 2000, Raymond S Brand wrote:

> Who should the docs be optimal for? The "first time user" or the "regular user"?
> I do not believe that the answer should be for the "first time user"; after all,
> they probably want/need a tutorial, not the reference manual.
>
> Yes, with the, currently, small number of modules, it's easy enough to just look
> through the list to find the module you need but what happens when the number of
> modules is not so small. Don't assume that all browsers have reasonable search
> facilities.
>
> If this index is going to go into the docs, then I suggest that it and the existing
> alphabetical module list both have links from the "top" index page. And to be
> complete, you should also create another directive index that categorizes the
> individual directives like you did the modules, and link the two directive
> indexes off the "top" index page.

Whatever. I gave my opinion, but I don't have strong feelings either way.
The main reason I did not retain the alphabetic index in my patch is that
I was trying to limit future maintenance work.

Re the Directives index, I also thought about that. My opinion is that it
would be very difficult to do a good job of it. Besides, by categorizing
the modules page you already get most of the way there, since the modules
themselves each index the directives that they contain. The only real
exception is the core "module" which contains a bunch of relatively
unrelated directives. It would probably be useful to add a categorized
index inside mod/core.html. Maybe I will do that someday if my patches
are ever committed ;-)

--
Joshua Slive
slive@finance.commerce.ubc.ca
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871

Joshua Slive wrote:
>
> I see at least a couple possible reasons why my doc patches are being
> ignored:
>
> 1. The people who have commit access don't like them, or think
> that they are not very important.
> 2. Nobody with commit access is reading the docs list, or has time
> to deal with submitted patches.

The implicit assumption seems to be that you expect only people
with commit access to comment, which I think is not a good one
to make.

All of your patches are still in my inbox, unfiled, until I
can get around to looking at them -- unless someone else commits
them before then.

> I'm just trying to see if I am wasting my time contributing here.
> Please let me know.

I personally do not think you're wasting your time -- but I also
would like to see more feedback and interaction on this list..
both regarding specific patch proposals and the documentation
in general.
--
#ken P-)}

Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>

Raymond S Brand wrote:
>
> The patch to htdocs/manual/mod/index.html, although useful in its
> own right, eliminates a useful index of modules sorted by module
> name.
>
> I recommend not accepting that patch as is.

How about having two sections on the page, one ordered functionally
and one lexically?
--
#ken P-)}

Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>

Raymond S Brand wrote:
>
> If this index is going to go into the docs, then I suggest that it
> and the existing alphabetical module list both have links from the
> "top" index page.

So are we leaning toward separate pages? One ordered lexically
(the current version) and one functionally?

> And to be> complete, you should also create another directive
> index that categorizes the individual directives like you did
> the modules, and link the two directive indexes off the "top"
> index page.

A good idea, but a lot more work. :-)

One problem with keeping separate lists is that there will
be a tendency for them to fall out of sync. We could do
some neat single-data-source things if we could use PHP or
the like, but we have to stay with basic HTML and some SSI
because of the mirrors and release packaging.
--
#ken P-)}

Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>

On Wed, 23 Aug 2000, Rodent of Unusual Size wrote:
> The implicit assumption seems to be that you expect only people
> with commit access to comment, which I think is not a good one
> to make.

I am sorry if it that's how my comments appeared. I am glad to have
feedback from everyone on the list. However, in the end, if there aren't
committers paying attention, it is all for naught.

>
> All of your patches are still in my inbox, unfiled, until I
> can get around to looking at them -- unless someone else commits
> them before then.

I am not a naturally patient person ;-) but I understand
you are busy. I'll try to be more patient in the future.

> I personally do not think you're wasting your time -- but I also
> would like to see more feedback and interaction on this list..
> both regarding specific patch proposals and the documentation
> in general.

I agree.

--
Joshua Slive
slive@finance.commerce.ubc.ca
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871

Rodent of Unusual Size wrote:
>
> Raymond S Brand wrote:
> >
> > If this index is going to go into the docs, then I suggest that it
> > and the existing alphabetical module list both have links from the
> > "top" index page.
>
> So are we leaning toward separate pages? One ordered lexically
> (the current version) and one functionally?

Yes.

> > And to be> complete, you should also create another directive
> > index that categorizes the individual directives like you did
> > the modules, and link the two directive indexes off the "top"
> > index page.
>
> A good idea, but a lot more work. :-)

That's why I didn't volunteer :-)

> One problem with keeping separate lists is that there will
> be a tendency for them to fall out of sync. We could do
> some neat single-data-source things if we could use PHP or
> the like, but we have to stay with basic HTML and some SSI
> because of the mirrors and release packaging.

Could definitely be a problem but the "many eyes" approach should
keep it mostly under control.


<Fair_Warning "What follows is an idea I have no time to implement>

An alternative to some form of dynamic content is build the directive
index pages and module index pages statically from a set of source
files.

Basic setup:
Create a doc source directory and populate it with a file
for each module.

Each module file contains the module name, short description,
list of functional areas, long description, and the
list of implemented directives in some parse-able
structure.

Each implemented directive in the list contains the directive
name, attributes, description, etc. in some parse-able
structure.

Build process:
A program loops through the files in the doc source directory
producing the static HTML doc pages. The program
should get run as part of the build process and could
also be run when creating the source tarballs.

Nice advantage:
Documentation for non ASF modules can be included in the end-users
doc tree easily.

</Fair_Warning>


Raymond S Brand