[documentation] Introduction and question about restructuring

[Lee Hunter]

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