perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stas Bekman <s...@stason.org>
Subject Re: Rearanging some content ?
Date Sat, 27 Apr 2002 18:16:48 GMT
Thomas Klausner wrote:
> Hi!

 > (althoug I don't know what
 > Stas thinks about totally rearanging his really great guide...).

One of the main reasons for moving the sources of the guide into 
modperl-docs and starting this whole documentation project is that I've 
had enough of this guide. It became too big for one person to maintain 
adding the need to work on guide 2.0. So my dream is to get people 
responsible for certain chapters and have the work load spread. I was 
planning to start seeking the chapter owners after we released the site. 
As early adopters you can choose your favorite chapters now :) IMO, it's 
better to have a single person responsible for a chapter, than group 
ownership. That way if the person is responsible the chapter will get 
all the attention it needs. Not sure if this will work for real, but we 
can experiment.

Therefore I won't you to consider the guide not mine anymore, and feel 
free to improve on it, though I'll keep my eye on it, at least in the 
beginning, so I know that the baby won't fall into the wrong hands :)

So all your ideas are great, Thomas. And let's start discussing the 
revamp of the things. It'll sure thing make the maintenance of the 
generic things easier.

> 
> Before I start to shuffle the content around, I'd like to ask for your
> opinion on the following issues:
> 
> What about splitting the Documentation into four sections:
> * mod_perl 1.0
> * mod_perl 2.0
> * general docs
> * offsite resources

+1

Probably should be:

* general
* 1.x specific
* 2.x specific
* other

> Currently, the 1.0-guide contains a lot of general information that is still
> valid under 2.0. I will now try to list all those sections, and where I
> would put them:
> * Perl Reference (docs/1.0/guide/perl.html)
>   -> move to: general docs

+1

> * Apache::+ modules (docs/1.0/guide/modules.html)
>   -> merge with The Apache/Perl Module List

not sure about that. Since the apache module list is special html 
distributed on CPAN, supposedly maintained by Doug. But we definitely 
can put the two next to each other.

Though another thing to think about is how all this going to map to 2.0. 
I'm not aware of a single non-core module that has been ported to 2.0 
(Other than Apache::Scoreboard, which I've ported but it's not commited yet)

> * Getting Help and further learing (docs/1.0/guide/help.html)
>   -> split up and
>      - move getting help with.. to "Getting help" (help/index.html)

careful with mod_perl version specific stuff. Not everything can be 
moved into the general place.

>      - move mailinglist infos to mailing-lists

that's obvious.

>      - move links to various sites to Offsite Resources

sure

> After looking through the guide a little bit - with the knowledge that it
> isn't a standalone product anymore - I'm starting to think that it might
> even be better to break the guid up even more (althoug I don't know what
> Stas thinks about totally rearanging his really great guide...).
> 
> e.g. there are a lot of very interesting sections (Performance tuning,
> Issuing HTPP headers, Controlling & monitoring the Server, OS & Hardware,
> Browser Bugs) that are more ore less mod_perl version indepentend. Some of
> the infos are availible in some other versions in mod_perl FAQs, too (e.g.
> Performace Tuning).

I think the faqs section should die. And those faqs that weren't merged 
into the guide (e.g. cvs guide) should be now merged into the new docs 
layout that you are talking about. So when we plan the revamp, think of 
getting rid of those.

> So what about breaking the whole doc-section down and rebuild it according
> to the four main sections mentioned above?
> 
> There won't be "the guide" anymore after this, so I'm not really sure wheter
> it is a good a idea or not...

+1

It's a good idea if you are up to make a commitment to finish it. There 
is a lot of work to do if you want to get it right. It's definitely a 
great idea, and I'd love to see it becoming true.

__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org


Mime
View raw message