Mailing List Archive: Module docs

Module docs

Sep 21, 2000, 12:08 PM

Post #1 of 4 (325 views)

As I think is evident, I am interested in improving the consistency (and
usability) of the module docs by putting them all in a standard format. I
have made a suggestion of a format (See message-id
<Pine.SOL.4.20.0009141601450.19470-300000@garibaldi.commerce.ubc.ca>)
but I really don't feel comfortable going ahead without some feedback.
I am sure that there are improvements that could be made, since I am
neither an HTML design expert, nor a documentation expert.

So, how about some of you lurkers out there on the list take a look and
make some suggestions. (Feedback from Apache group members is obviously
acceptable as well.)

The format I suggested is just about as close as possible to the format
that many of the module docs are already in. Is more detail needed? Less
detail? Should we be looking at a non-html format (DocBook, XML,
whatever...). Should it be "flashier" like mod_rewrite.html?

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

Re: Module docs [ In reply to ]

rbowen at rcbowen

Sep 21, 2000, 12:34 PM

Post #2 of 4 (320 views)

Permalink

Joshua Slive wrote:
>
> As I think is evident, I am interested in improving the consistency (and
> usability) of the module docs by putting them all in a standard format. I
> have made a suggestion of a format (See message-id
> <Pine.SOL.4.20.0009141601450.19470-300000@garibaldi.commerce.ubc.ca>)
> but I really don't feel comfortable going ahead without some feedback.
> I am sure that there are improvements that could be made, since I am
> neither an HTML design expert, nor a documentation expert.
>
> So, how about some of you lurkers out there on the list take a look and
> make some suggestions. (Feedback from Apache group members is obviously
> acceptable as well.)
>
> The format I suggested is just about as close as possible to the format
> that many of the module docs are already in. Is more detail needed? Less
> detail? Should we be looking at a non-html format (DocBook, XML,
> whatever...). Should it be "flashier" like mod_rewrite.html?

I liked it. It was very much in line with what I wished was there when I
was reading through all the docs - that is, making every doc look the
same, so you can count on certain information. Individually, most of the
docs are just fine, but taken as a whole, the inconsistency really gets
to me.

Rich

Re: Module docs [ In reply to ]

Ken.Coar at Golux

Sep 21, 2000, 12:34 PM

Post #3 of 4 (318 views)

Permalink

Joshua Slive wrote:
>
> Should we be looking at a non-html format (DocBook, XML,
> whatever...).

Whatever we use needs to be 'final form' in order to be usable
at the mirrors.

> Should it be "flashier" like mod_rewrite.html?

I'd prefer not.
--
#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: Module docs [ In reply to ]

dot at dotat

Sep 21, 2000, 12:52 PM

Post #4 of 4 (319 views)

Permalink

Joshua Slive <slive@finance.commerce.ubc.ca> wrote:
>As I think is evident, I am interested in improving the consistency (and
>usability) of the module docs by putting them all in a standard format. I
>have made a suggestion of a format (See message-id
><Pine.SOL.4.20.0009141601450.19470-300000@garibaldi.commerce.ubc.ca>)
>but I really don't feel comfortable going ahead without some feedback.

It looked fine to me. I say go ahead!

Tony.
--
en oeccget g mtcaa f.a.n.finch
v spdlkishrhtewe y dot@dotat.at
eatp o v eiti i d. fanf@covalent.net