On Fri, 30 Nov 2001, Andrew Olden wrote: > > As a bit of an outsider to the Apache Docs project, my 2 euros are: > > What kind of docs are we/you trying to write? Docs for penguin heads so > that > > they can squeeze out a few more features from Apache, or docs for numpties > > who just want to get a webserver up and running? > > > > To write a single document to appeal to both is essentially impossible; > so, > > do you write two separate documents? Sounds like the work load is > doubling > > with this option. How about a few 'scenarios' which will cater for the > bulk > > of people who just want to do the basics. > > eg. "I'm running an intranet and want to share docs internally" > > "I want to set up a simple public webserver with no script support" > > "I want an all singing and all dancing, cgi-enabled, Virtual Hosting > > environment with .htaccess and frontpage support". > > > > Too much hand-holding? I'll leave that up to you to decide. Oh yes, > please > > don't shoot me down (unless you can do it in a funny way).
After thinking about this quite a bit, I think that these comments are right on target. We are indeed writing two rather different sorts of documentation, and I think that having this clearly in mind, and doing it intentionally, would be a good thing. The FAQ goes part way to doing this - taking specific scenarios, and addressing how one would deal with particular situations - and it does a really good job of it in most cases. And the various tutorials seem to do this pretty well, although there are very few of them at this time. We're not really writing two separate documents, as they are, and should be, deeply interlinked. But if we are aware as we work on these that we are talking to two completely different audiences, I think that it will result in better docs. I still maintain that we cannot, and should not try to, document every other product that someone will need to work with in order to run Apache. (For example, bind, sendmail, perl, and so on.) Other folks do that, with varying degrees of success. And it's a bottomless pit once you start going down it. Are they running bind? What if they are running Windows DNS? How about djbdns? And who knows what else? And all that just to tell them how to set up a virtual host? But we can point folks to the right resources to solve those sorts of problems. -- Rich Bowen - [EMAIL PROTECTED] Author - Apache Server Unleashed - http://www.apacheunleashed.com/ --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
