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: New Structure - Suggestion
Date Sun, 28 Apr 2002 06:36:24 GMT
Thomas Klausner wrote:
> Hi!
> 
> Here is a suggestion for the new structure of the content:
> (as your MUAs will probably break the long lines and tab-spacing, I've
> additionally attached it..)

> Now, lets move around some docs:
> (Nota Bene: I'm not sure if all of the stuff I move out of 1.x is correct for 2.x ...
Maybe stating somewhere that all of the docs here assume mod_perl 1.x unless otherwise stated
would be a good idea)
> (There's a new structure diagram following, so you don't have to keep track
> of all the moves :-)

no, better don't move out anything specific to 1.x.

+1 on everything but things I've commented on:

> - Split download::source into stable_source and cvs, replace the cvs-section of download::source
with faq::mod_perl_cvs
> 
> - Rearrange the Docs main sections to:
>   * General documentation
>   * Tutorials (or maybe "Tips & Tricks" would be a better name..)
>   * mod_perl 1.x Documentation
>   * mod_perl 2.x Documentation
>   * Other Documentation Resources

The 1.x and 2.x docs *are* tutorials in contrast with APIs.  Also "tips 
and tricks" are most likely won't be the same for 1.x and 2.x.

The "Tutorials" section ishould go one before last. more comments below.

> - Move to "General docs":
>   * 1.x::guide::Perl_Reference
>   * 1.x::guide::ISPs

this one is version specific. e.g. su-exec mod_perl will be possible in 
2.0. But probably it's OK to have "some" version specific notes in the 
general docs. As long as the "but in version x this is done ..." entries 
are very few, should be ok.

>   * 1.x::guide::Controlling_Monitoring

the same as above. but +1 to try, will move back if we see too many 
version specific notes.

>   * 1.x::guide::OS_Hardware
>   * 1.x::guide::Advocacy


>   * 1.x::guide::cgi_to_mod_perl_porting (?? not sure with this)

this one >> /dev/null

>   * 1.x::faq::perl_myths

ok

>   * 1.x::faq::faq

most likely > /dev/null

> - Move to "Tutorials":
>   * 1.x::guide::HTTP_Headers
>   * 1.x::guide::RDBMs
>   * 1.x::guide::dbm_files
>   * 1.x::guide::code_snippets (should maybe stay in mod_perl 1.x ?)
>   * 1.x::guide::security (although it should be renamed to "Using Authentification to
protect your site" or something ..)
>   * 1.x::guide::performance_tuning

They are all version specific, cannot move.

>   * 1.x::faq::performance_tuning

 >> /dev/null

>   * 1.x::guide::browers_bugs
>   * 2.x::guide::tutorial::templating

+1

> - Delete:
>   * 1.x::guide::Frequent_problems (contains only to links to problems answered somewhere
else)

-1, that's exactly the idea behind this doc, a grouped by topic 
troubleshooting section.

>   * 1.x::guide::overview (or rewrite it to fit new structure)

+1 to delete, the "description" section in each chapter is doing the work.

>   * 1.x::guide::introduction (but credits and some content (mod_cgi,..) somewher else
(maybe make a new page, "contributors", or "people behind mod_perl"..))

+1 to first make a split into introduction (must stay in 1.x for now) 
and credits. then we will see.

>   * 1.x::faq::mod_perl (this is just a very condensed version of the site)
>   * 1.x::faq::cgi_to_mod_perl (redundant)
>   * 1.x::faq::mod_perl_cgi (redundant)
>   * 1.x::faq::traps (redundant)
>   * 1.x::faq::API (redundant)

+1

> - Move 1.x::guide::AppendixA to a new section in download "Download additional, usefull
SW" or something

+1

> - Split up guide::getting_help_further_reading to "mailing lists", "offsite resources"
and "getting help"

this can go the general mod_perl docs. And have a small help.pod in the 
1.x and 2.x point there.

> 	Win32 Platforms

(this was missed from the changes discussion). win32/ should be moved 
into 1.0/guide, we will have a similar platform specific notes in 2.x.

Another thing to think about is whether to do the same thing I've 
started with docs/2.0: drop the "guide" dirname and split docs into user 
and devel. But not sure if we really have any 1.x devel specific docs.

by 'devel' I call low-level things like hacking on mod_perl core, 
irrelevant to the user. so probably just s/guide/user/.

__________________________________________________________________
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