[documentation] Introduction and question about restructuring

[Addison Berry]

Hi Lee and welcome!

I don't have time for complete response as Steven has thankfully taken  
the time to do.  I did want to point out though that there is  
drupal.org reorganization group and there is a specific thread about  
the Handbook landing page (http://groups.drupal.org/node/6568) which  
you may want to jump on as well.

This is the overview doc thread that Steven referred to, http://drupal.org/node/180296 
.  Jay (nitrospectide) put lots of effort into it and It has some  
great stuff in it. I am fighting to find time to give a thoughtful  
review/response.  More eyes on that would be lovely.

- Addi

On Dec 5, 2007, at 3:32 PM, Lee Hunter wrote:

> As a new member of the documentation team and this mailing list, I
> wanted to introduce myself and then ask you folks about the particular
> itch that I'd like to scratch.
>
> I've been a writer and editor for over thirty years, that includes
> seven as the founder and managing editor of a specialized computer
> magazine and for the last eight years or so I've been a technical
> editor in the software industry. Much of my recent work has involved
> editing documentation for enterprise web and back-end applications.
> The largest project I've done was editing the Adobe Acrobat 8 SDK
> which was 30 odd books covering roughly 10,000 pages of deathless
> prose.
>
> I've been keenly interested in CMS applications since the Frontier
> days and actually did a little volunteer editing on The Zope Book but
> its only recently that someone has been foolish enough to actually pay
> me to set up a real CMS from scratch. Using Drupal, of course.
>
> So that brings me to my itch. I've been puzzled and a little
> frustrated by the way the Drupal doc set is organized. I'm used to
> seeing documentation that is organized first by audience or role and
> then by groups of related tasks or objectives. In other words, you'll
> typically see an admin guide, user guide, developer guide etc and
> within, say, the admin guide you'll have a chapter called something
> like "Managing Users" which brings together all the overview and
> procedural information that the admin will need to be successful in
> adding, removing, modifying user data. Each chapter typically has an
> overview which explains what is in the chapter and perhaps provides
> any conceptual information that might be needed to carry out the
> procedures.
>
> In the case of Drupal, it seems that admin and site building
> information is jumbled together in no particular order. I would think
> that all the administration information (managing backups, users,
> Apache, databases, general Drupal settings etc.) should go in a
> separate document and all the non-developer stuff about building your
> own Drupal site (themes, creating content types, CCK, Views etc.)
> should go together. Related tasks need to be grouped together in
> something like a chapter or section and placed in a logical sequence.
>
> I was  thinking that I should just put this in the issue queue along
> with a tentative set of TOCs but because I'm relatively new to the
> community and this
>         would really be a major change in the information
> architecture,
>          I thought I'd raise it here first in case I'm duplicating
> other efforts or proposing something that has already been examined
> and discarded. Or possibly there's another way that I should be
> proceeding.
>
> Anybody have any thoughts? Is this worth pursuing?
>
> Lee Hunter
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/