[documentation] Introduction and question about restructuring

[Steven Peck]

Seeing alternatives is always ok.

The current set of handbooks have evolved organically.  Also adding
cloudiness is the fact that Drupal doesn't have a separate 'back end'
admin section.  It has a progressive set of permissions that expose
additional items as you have more rights which depending on your site
may not bear any relationship to someone else' site.

The documentation has also not been traditionally written for 'end
users'.  It has been written for site developers and implementors.
The site implementor/developer has been expected to provide the end
user documentation specific to their sites implementation.

The documentation has also grown a lot.  Organically.

Right now we have some areas that have suffered as a result of that.
The development handbook has received some specific updates in the
form of docs on CVS and Project maintenence and such, but is that
isn't really related to general module development.... No one has had
time to go through and look at restructuring it.

The Getting Started section was completely rewritten to provide a base
foundation to 'Get Started' and nothing more.  It is also the 'base
level' target for updating per Drupal release.  The base documentation
for this section is also in DocBook so we can generate PDF versions
and have it live in CVS.

The customization section is a collection of buckets for various
contributed content.  Some very detailed tutorials, some one page how
to articles.  There was a goal a long time ago to get contrib modules
documented and updated on a regular basis but that has proven to be
unreasonable in the long term.  This section doesn't really have
structure beyond broad categorizations.  This is on purpose as no one
has had better ideas.

We have a new theme guide for Drupal 6 which is not obviously linked
to yet (but anyone familiar with Drupal book URLs can find it).

Recently someone provided a nice 'structural overview' of Drupal doc
in the issue queue.  I am waiting on a technical review of it, then I
am going to re-org the /handbook page with that as the lead in link.

The handbook have had about 3-4 major structural changes in the last
few years (mostly mine).  Each time we exposed more information and
the very nature of the forum questions changed.  I tried once to
structure it in a way similar to what you mention but site building
and administering a site are tightly inter woven and I couldn't figure
it out.   Drupal has also changed the /admin interface since last I
tried that.  It may also be the fact that I am not a professional
writer though I do write a lot of support documentation in the course
of my job so people don't call me with support questions or I can just
send them something.

So, summary.... Getting Started guide as a focused resource stays.  I
am certainly open to ideas on making it better, but it needs to retain
a specific focus on Drupal core.  See the PDF for it, the online
version is subject to a little meshing of Drupal versions.

Anything else.... let's here it.

Steven Peck
Documentation Lead
http://www.blkmtn.org

On Dec 5, 2007 12:32 PM, Lee Hunter <lee.hunter at hum.com> 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/
>