Re: [PATCH] Second try: External Apache tutorials and mod/index.htmlreorg

[Raymond S Brand <rs...@gate.net>]

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

Re: [PATCH] Second try: External Apache tutorials and mod/index.htmlreorg

[Raymond S Brand <rs...@gate.net>]

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

Re: [PATCH] Second try: External Apache tutorials and mod/index.htmlreorg

[Rodent of Unusual Size <Ke...@Golux.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/>

Re: [PATCH] Second try: External Apache tutorials and mod/index.htmlreorg

[Joshua Slive <sl...@finance.commerce.ubc.ca>]

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