Mailing List Archive

Michele Petrovsky wrote:
>
> One more thing - everyone I've sounded out re: this (all
> of whom are sysadmins and at least Unix-conversant) has said
> that the one piece of Apache documentation they'd most like
> to have would be an "in-English" version of the existing
> online docs - something akin to a fleshed-out Quick Reference
> Card. So I guess we're back to considering a "Users' Guide"
> too.
>

PMFJI :]

I would have to say, in my opinion, that the Apache Docs are
great 'starter' guides in general but DO NOT cover things at a
length that I am looking for - especially when it comes to
things like some of the modules - mod_rewrite, for example.

Also, at least in my local area, the people I've discuss things
similar to this with have found that what they 'think' about
how things happen in Unix, etc, are not really the way things
work in Unix, etc. So some of the confusion when it comes
to WWW servers, etc is that they must unlearn what they have
learned and start thinking in a wider scope.

Thx for hearing out my 2 Cents :]
-Sneex-
______________________________________________________________________
Bill Jones | 904/632-3089 | http://www.fccj.org/cgi/mail?webmaster

Contrary to the general lack of support within 'Open Source' coding -
I support what I write... Others haven't, can't, or won't...

In my experience the Apache docs are good once you get to know them, but
they require a bit of getting used to. We're in a difficult situation right
now because we're all (I assume) fairly comfortable with the docs and the
other resources available (ApacheWeek, for example). All of this time we've
spent with Apache has probably made us blind to the problems a novice will
face just looking at the docs for the first time.

Maybe what we're talking about is a very general tutorial about Apache
itself. How the server works, what modules are, what the components of CGI
are and how they can work with Apache (mod_perl, etc.). What about putting
this very general guide together so people who are just starting to look at
various web servers don't have to really struggle to get a grasp on what
Apache is and does.

As for the more in-depth documents (ie. mod_rewrite) those are the sorts of
things that should be tackled as they are starting to be understood... that
way, you get all the answers to your newbie questions, and have the docs
written before you forget the niggling details.

Comments?

Jon

Jon MacKay
jmackay@rim.net
http://www.rim.net


> I would have to say, in my opinion, that the Apache Docs are
> great 'starter' guides in general but DO NOT cover things at a
> length that I am looking for - especially when it comes to
> things like some of the modules - mod_rewrite, for example.
>
> Also, at least in my local area, the people I've discuss things
> similar to this with have found that what they 'think' about
> how things happen in Unix, etc, are not really the way things
> work in Unix, etc. So some of the confusion when it comes
> to WWW servers, etc is that they must unlearn what they have
> learned and start thinking in a wider scope.
>
> Thx for hearing out my 2 Cents :]
> -Sneex-
> ______________________________________________________________________
> Bill Jones | 904/632-3089 | http://www.fccj.org/cgi/mail?webmaster
>
> Contrary to the general lack of support within 'Open Source' coding -
> I support what I write... Others haven't, can't, or won't...

Excellent point indeed. I had just installed Apache 1.3 on a secondary web
server a little over a week ago and found it very easy to install, and seems
very flexible. One of the reasons I contacted Michelle about participating
in her project last week after reading her post to this mailing list, was
because I was a little disappointed about the availability of non-commercial
documentation available for Apache. To you all who are familiar with it, it
may seem adequate, but to a system administrator who's only worked with MS
applications, it is no where near adequate. As we all know, MS does things
a bit differently than the rest of the world, and it was a bit of a culture
shock for me.

Still, I adopted Apache into my network because I wanted to broaden my
knowledge, and I had always heard that Apache was an excellent web platform.
I had less trouble installing and running Apache, than I did with IIS4!
Maybe trouble isn't the appropriate word, but it took less effort certainly
to run Apache initially.

I'm looking forward to working with Michelle on her project, and hope to
learn much from you all. I have plans to install more Apache servers on NT4
systems, and have may install it on our Solaris servers as well.

I think you hit the mark right on the head with your comments regarding
tutorials. That is indeed exactly what is needed. I will be gone on
business for the next week or so, but when I return, I hope to begin fully
participating in the project.

Warmest Regards,
-----
Anthony Abby
Operations Manager - A Plus Data Services
http://www.aplusdata.com/

Competitively priced web hosting and development solutions
A Plus Data Services - The Basic Building Block of your Internet Life!



> -----Original Message-----
> From: apache-docs-owner@apache.org
> [mailto:apache-docs-owner@apache.org]On Behalf Of Jon MacKay
> Sent: Tuesday, December 01, 1998 11:14 AM
> To: 'apache-docs@apache.org'
> Subject: RE: Case Studies
>
>
> In my experience the Apache docs are good once you get to know them, but
> they require a bit of getting used to. We're in a difficult
> situation right
> now because we're all (I assume) fairly comfortable with the docs and the
> other resources available (ApacheWeek, for example). All of this
> time we've
> spent with Apache has probably made us blind to the problems a novice will
> face just looking at the docs for the first time.
>
> Maybe what we're talking about is a very general tutorial about Apache
> itself. How the server works, what modules are, what the components of CGI
> are and how they can work with Apache (mod_perl, etc.). What about putting
> this very general guide together so people who are just starting
> to look at
> various web servers don't have to really struggle to get a grasp on what
> Apache is and does.
>
> As for the more in-depth documents (ie. mod_rewrite) those are
> the sorts of
> things that should be tackled as they are starting to be
> understood... that
> way, you get all the answers to your newbie questions, and have the docs
> written before you forget the niggling details.
>
> Comments?
>
> Jon
>
> Jon MacKay
> jmackay@rim.net
> http://www.rim.net
>
>
> > I would have to say, in my opinion, that the Apache Docs are
> > great 'starter' guides in general but DO NOT cover things at a
> > length that I am looking for - especially when it comes to
> > things like some of the modules - mod_rewrite, for example.
> >
> > Also, at least in my local area, the people I've discuss things
> > similar to this with have found that what they 'think' about
> > how things happen in Unix, etc, are not really the way things
> > work in Unix, etc. So some of the confusion when it comes
> > to WWW servers, etc is that they must unlearn what they have
> > learned and start thinking in a wider scope.
> >
> > Thx for hearing out my 2 Cents :]
> > -Sneex-
> > ______________________________________________________________________
> > Bill Jones | 904/632-3089 | http://www.fccj.org/cgi/mail?webmaster
> >
> > Contrary to the general lack of support within 'Open Source' coding -
> > I support what I write... Others haven't, can't, or won't...
>

At 11:13 AM 12/1/98 -0500, you wrote:
>In my experience the Apache docs are good once you get to know them, but
>they require a bit of getting used to.

Very true.

>We're in a difficult situation right
>now because we're all (I assume) fairly comfortable with the docs
>and the other resources available (ApacheWeek, for example).
> All of this time we've
>spent with Apache has probably made us blind to the problems
>a novice will face just looking at the docs for the first time.

That's been the message I've been getting
from people I've talked to.

>
>Maybe what we're talking about is a very general tutorial about Apache
>itself. How the server works, what modules are, what the components
>of CGI
>are and how they can work with Apache (mod_perl, etc.).
>What about putting this very general guide together so people who are just
starting to look at
>various web servers don't have to really struggle to get a grasp
>on what Apache is and does.

Once again, a very good point.

>
>As for the more in-depth documents (ie. mod_rewrite) those are the
>sorts of things that should be tackled as they are starting to be
>understood... that way, you get all the answers to your newbie
>questions, and have the docs written before you forget
>the niggling details.
>

This is where questions as to structure, presentation,
audience etc. start to crop up. Once there's a good
general in-English tutorial of the type you've described,
a case could be made that the existing docs are sufficient
for all other needs (e.g., sysadmins, programmers).
So, should apache-docs concentrate solely on:

* producing a tutorial
* broadening/facilitating access to the
existing docs (e.g., a document "portal"
as has been suggested; creating numerous
format versions such as PDF, SGML)

or do we need other levels/types of documentation?
And if the latter, what?

Michele

At 11:24 AM 12/1/98 -0500, you wrote:
>Excellent point indeed. I had just installed Apache 1.3 on a secondary web
>server a little over a week ago and found it very easy to install, and seems
>very flexible. One of the reasons I contacted Michelle about participating
>in her project last week after reading her post to this mailing list, was
>because I was a little disappointed about the availability of non-commercial
>documentation available for Apache. To you all who are familiar with it, it
>may seem adequate, but to a system administrator who's only worked with MS
>applications, it is no where near adequate. As we all know, MS does things
>a bit differently than the rest of the world, and it was a bit of a culture
>shock for me.

This is always my first concern; it's even a little bit
of a crusade for me. Any effort to broaden the acceptance
and use of Open Source Software (like Apache, Linux, WINE)
must, I feel, address the MS world.

>Still, I adopted Apache into my network because I wanted to broaden my
>knowledge, and I had always heard that Apache was an excellent web platform.
>I had less trouble installing and running Apache, than I did with IIS4!

Me too, and it's good to know that someone with
a strong MS backgrouynd (as opposed to somebody like me
who's sort of a Unix/MS hybrid) has had these kinds of headaches.

>Maybe trouble isn't the appropriate word, but it took less effort certainly
>to run Apache initially.
>
>I'm looking forward to working with Michelle on her project, and hope to
>learn much from you all. I have plans to install more Apache servers on NT4
>systems, and have may install it on our Solaris servers as well.

Way cool; the scope/foundation not only of case
studies but even of tutorials would be that much
more solid and valid if we can include as many OS
environments as possible.

Look's like the life is back into it :o)



> * broadening/facilitating access to the
> existing docs (e.g., a document "portal"
> as has been suggested; creating numerous
> format versions such as PDF, SGML)
> or do we need other levels/types of documentation?
> And if the latter, what?

I would suggest a Pure, Html Based Documenation with a logical
,splittable,Structure

- Thereby elimination various layout overload, thus focussing on the
Main goal
- Downloadable in parts, making it browsable offline, on there own
Home Server , thus elemenating the need of pdf


As far as 'if read point 1 till 4 is accepted for the portal, and we'r still
doubting about point 5.


- Reinder

Jon MacKay wrote:
>
>
> Maybe what we're talking about is a very general tutorial about Apache
> itself. How the server works, what modules are, what the components of CGI
> are and how they can work with Apache (mod_perl, etc.). What about putting
> this very general guide together so people who are just starting to look at
> various web servers don't have to really struggle to get a grasp on what
> Apache is and does.

:]

Agreed, this is where the Apache Doc project could start; however, after
reading and considering Anthony's, Michele's, et al comments - my question
would be, I suppose, does the group feel the current Docs are weak in
general scope or just in their treatment of MS environments in general?


>
> As for the more in-depth documents (ie. mod_rewrite) those are the sorts of
> things that should be tackled as they are starting to be understood... that
> way, you get all the answers to your newbie questions, and have the docs
> written before you forget the niggling details.

A generally strong foundation is best before attacking
intermediate/advanced topics, etc.


>
> Comments?
>

(I think this group is starting to simmer a little better :)

-Sneex- :]
______________________________________________________________________
Bill Jones | 904/632-3089 | http://www.fccj.org/cgi/mail?webmaster

Contrary to the general lack of support within 'Open Source' coding -
I support what I write... Others haven't, can't, or won't...

At 02:06 PM 12/1/98 -0500, you wrote:
>Jon MacKay wrote:
>>
>>
>> Maybe what we're talking about is a very general tutorial about Apache
>> itself. How the server works, what modules are, what the components of CGI
>> are and how they can work with Apache (mod_perl, etc.). What about putting
>> this very general guide together so people who are just starting to look at
>> various web servers don't have to really struggle to get a grasp on what
>> Apache is and does.
>
>:]
>
>Agreed, this is where the Apache Doc project could start; however, after
>reading and considering Anthony's, Michele's, et al comments - my question
>would be, I suppose, does the group feel the current Docs are weak in
>general scope or just in their treatment of MS environments in general?
>

I'd say limited in scope, insofar as they assume familiarity with
Unix and TCP/IP concepts at least. The need to address the MS
audience pertains more to strategy than functionality.

>>
>> As for the more in-depth documents (ie. mod_rewrite) those are the sorts of
>> things that should be tackled as they are starting to be understood... that
>> way, you get all the answers to your newbie questions, and have the docs
>> written before you forget the niggling details.
>
>A generally strong foundation is best before attacking
>intermediate/advanced topics, etc.
>

Absolutely.

On Tue, 1 Dec 1998, Michele Petrovsky wrote:

> This is where questions as to structure, presentation,
> audience etc. start to crop up. Once there's a good
> general in-English tutorial of the type you've described,
> a case could be made that the existing docs are sufficient
> for all other needs (e.g., sysadmins, programmers).
> So, should apache-docs concentrate solely on:
>
> * producing a tutorial
> * broadening/facilitating access to the
> existing docs (e.g., a document "portal"
> as has been suggested; creating numerous
> format versions such as PDF, SGML)
>
> or do we need other levels/types of documentation?
> And if the latter, what?

I'd love to see how-to type documents answering to very practical problems
like user wants to use SSI how do I enable it or I don't want all people
to see my private pages how do I stop them.
Those are for buzy (and maybe lazy) part time admins, like me. But
tutorials would be great also covering things more in depth and paving
path to "conventional" apache documentation use.

This is my first appearance on list so I might introduce myself a bit. My
main job is to develop searh system with Java. I also admin departments
apache server on solaris. I need web-server in my work so my desktop is
Linux with apache and jserv (apache servlet module).

---
Harri Kemppainen cshake@uta.fi
Java-programmer Attila B288b
Information Studies, University of Tampere +358 3 215 7632

At 11:07 AM 12/2/98 +0200, you wrote:
>On Tue, 1 Dec 1998, Michele Petrovsky wrote:
>
>> This is where questions as to structure, presentation,
>> audience etc. start to crop up. Once there's a good
>> general in-English tutorial of the type you've described,
>> a case could be made that the existing docs are sufficient
>> for all other needs (e.g., sysadmins, programmers).
>> So, should apache-docs concentrate solely on:
>>
>> * producing a tutorial
>> * broadening/facilitating access to the
>> existing docs (e.g., a document "portal"
>> as has been suggested; creating numerous
>> format versions such as PDF, SGML)
>>
>> or do we need other levels/types of documentation?
>> And if the latter, what?
>
>I'd love to see how-to type documents answering to very practical problems
>like user wants to use SSI how do I enable it or I don't want all people
>to see my private pages how do I stop them.
>Those are for buzy (and maybe lazy) part time admins, like me. But
>tutorials would be great also covering things more in depth and paving
>path to "conventional" apache documentation use.

I find this example particularly interesting because
it's pretty much a word-for-word description of what
the sysadmin at the college where I teach is working on
right now. Fine-tuning of various sorts might make
for a very useful category of howto docs. So here's
a question: what other specific types of howtos might
we include in such a category?

>This is my first appearance on list so I might introduce myself a bit. My
>main job is to develop searh system with Java. I also admin departments
>apache server on solaris. I need web-server in my work so my desktop is
>Linux with apache and jserv (apache servlet module).
>

Okay, looks like we've really got things rolling...

From the discussion so far, here's the catagories we've come up with:

* How-to -- quick and dirty for those new to Apache
* How-to 2 -- advanced topics, more than you thought you'd ever need
to know...
* Tutorial / Overview of Apache -- glossary of terms, what apache
offers, how it works (generally), why use it...
* A tutorial specific for those setting up Apache on MS?? (never done
it, know nothing about this...)

At least I think this is everything.....

I like the idea of starting from a "solid foundation", but as we're all
working with these servers, we'll probably end up getting a few revisions of
the how-to's here and there too. Personally, though, I'm interested in
starting in on the Tutorial / Overview....

As for documentation, I also favour just plain and simple HTML. If need be
I've transferred HTML to PS fairly painlessly, and from there we can go to
PDF without much work. It's a question of need though; if we convert things
to PDF they should be either a quick ref. card, or general overview
materials (ie. materials someone may have to show a "higher-up" before
moving to Apache as their server.)

Jon



> -----Original Message-----
> From: Michele Petrovsky [SMTP:petrovsk@voicenet.com]
> Sent: Wednesday, December 02, 1998 9:26 AM
> To: apache-docs@apache.org
> Subject: RE: Case Studies
>
> At 11:07 AM 12/2/98 +0200, you wrote:
> >On Tue, 1 Dec 1998, Michele Petrovsky wrote:
> >
> >> This is where questions as to structure, presentation,
> >> audience etc. start to crop up. Once there's a good
> >> general in-English tutorial of the type you've described,
> >> a case could be made that the existing docs are sufficient
> >> for all other needs (e.g., sysadmins, programmers).
> >> So, should apache-docs concentrate solely on:
> >>
> >> * producing a tutorial
> >> * broadening/facilitating access to the
> >> existing docs (e.g., a document "portal"
> >> as has been suggested; creating numerous
> >> format versions such as PDF, SGML)
> >>
> >> or do we need other levels/types of documentation?
> >> And if the latter, what?
> >
> >I'd love to see how-to type documents answering to very practical
> problems
> >like user wants to use SSI how do I enable it or I don't want all people
> >to see my private pages how do I stop them.
> >Those are for buzy (and maybe lazy) part time admins, like me. But
> >tutorials would be great also covering things more in depth and paving
> >path to "conventional" apache documentation use.
>
> I find this example particularly interesting because
> it's pretty much a word-for-word description of what
> the sysadmin at the college where I teach is working on
> right now. Fine-tuning of various sorts might make
> for a very useful category of howto docs. So here's
> a question: what other specific types of howtos might
> we include in such a category?
>
> >This is my first appearance on list so I might introduce myself a bit. My
> >main job is to develop searh system with Java. I also admin departments
> >apache server on solaris. I need web-server in my work so my desktop is
> >Linux with apache and jserv (apache servlet module).
> >
>

On Wed, 2 Dec 1998, Jon MacKay wrote:

> As for documentation, I also favour just plain and simple HTML. If need be
> I've transferred HTML to PS fairly painlessly, and from there we can go to
> PDF without much work. It's a question of need though; if we convert things
> to PDF they should be either a quick ref. card, or general overview
> materials (ie. materials someone may have to show a "higher-up" before
> moving to Apache as their server.)

You might want to consider SDF (http://www.mincom.com/mtr/sdf/).
It's free and generates nice HTML, as well as many other formats.

Ian (SDF's author).

Ian Clatworthy wrote:
>
> You might want to consider SDF (http://www.mincom.com/mtr/sdf/).
> It's free and generates nice HTML, as well as many other formats.
>
> Ian (SDF's author).


Oh, that reminds me of something!

I, for one, am glad to see this URL again :]

Thx!
-Sneex-