[documentation] Handbook re-org

[Frando]

Hey, great ideas all this. 
So, am I right in assuming that the versioned "Installation etc" parts in 
your outline are just the imported docbook docs from CVS (for 5 and 6)? 
That would be great, and should be clearly noted or highlighted (so that 
there is a visible split between "official" and "contributed" docs on d.o).

Snippets, How-Tos and videocasts should probably be versioned, too. 
Outdated how-tos on d.o. have led to problems several times (teaching 
bad habits etc). For new major versions, how-tos and snippets that 
are still valid could just be copied over.z

Regarding the current "Developing for Drupal" handbook. I would strongly 
suggest to split this into a reference-style development handbook, and a
nother book that contains stuff like the "contributing" section, the
d.o/CVS/
Project/Diff/Patch usage section, benchmarking how-tos etc. If
Docbook-In-CVS 
works out well for the Installation/Configuration part, a great thing would
be, 
as a next step, to maintain the reference part of the development docs (
from the current outline that would be "Module developer's guide" (most
parts), 
"Drupal's APIs", "Install profile developer's guide", maybe "Coding
standards" 
and "Writing secure code" as appendices) as docbook in CVS as well. We need 
these parts to be versioned anyway, and having a streamlined, referential 
document for developers seems like a great idea.

That would leave us with something like this:

- Installation and Configuration
    (from CVS/docbook)
- Customization 
    (contrib module docs, snippets, how-tos etc)
- Theme developer's guide
- Drupal development guide
    (module dev guide, install profile dev guide, drupal's apis, ... - if
possible 
     at some point also versioned and from CVS/docbook)
    + some section for contributed development docs
- Developing for Drupal (possibly needs a better title)
    (contributing, d.o/project/cvs/diff/patch usage, benchmarking how-to, 
    coding standards, etc)
- Drupal site resources

Seems to be quite intuitve for me.

best regards,
Frando


Steven Peck-2 wrote:
> 
> Ok.  I went through several edits and misc other stuff but keep
> running into time crunches and distractions....
> 
> So let's just toss out broad outlines.  The first book will no longer
> be the existing 'About Drupal'
> We'll start with the base, "Installation and configuration".  Yes
> there will be some cross over stuff here but we can deal with it.
> 
> As it is designed to somewhat version specific with parts that are not
> we can sort of split it.
> * Getting Started *
> - Project and features
> - Before you start
> - Drupal 6
> +- Installation etc
> - Drupal 5
> + - Installation etc
> - Drupal 4.7
> + - This will contain many of the older pages that aren't getting
> unpublished.
> -Concepts
> - - Collected articles etc.
> 
> BTW ( Addison's ideas were better then mine so here they are)
> * HowTos and Snippets*
> - HowTos
> + - The advanced user guide
> + - Site recipes
> + - Theme tutorials
> + - Contrib module HowTos
> - Snippets (partial solutions, bits and pieces)
> + - Introduction to the concept / use / risks
> + - PHP Snippets
> + - PHP Template Snippets
> + - Contributed modules
> - Videocasts
> 
> 
> * Theme developers guide *
> -Theming overview - introduce things.
> + - Engines overview engines with a lean towards phptemplate
> + I get fuzzy on the details after this part.  There aare differences
> between 4.7-5.0 and 6.0.  dvessel is actually writing theme docs for
> D6 right now separately so we have a start right there for some what
> versioned docs.  How to integrate them in a sane manner still needs
> some thought and response.
> 
> * Developing for Drupal *
> Currently I am not planning on touching this yet.  I do have some
> ideas on it but just re-organizing two and integrating a third is
> enough initial scope.  There are two main areas in this book though.
> One is module development, the other is drupal.org project use and
> maintenance of projects/cvs/etc.  So it may be good to give it some
> thought for later.
> 
> * Drupal Site Resources * or some such inclusive title.
> This pulls in the stuff that was in About Drupal.
> The About Drupal documentation goes in.
> 
> I have more thoughts but am stopping here
> 
> Steven Peck
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
> 

-- 
View this message in context: http://www.nabble.com/Handbook-re-org-tf4381700.html#a12507418
Sent from the Drupal - Doc mailing list archive at Nabble.com.