[documentation] Some Background/Strategy Help Needed re: "DrupalCookbook"

[Nancy Wichmann]

I am “I.”  I wrote in that tone to give the intended audience (beginners, as
I was at the time) more of a feeling that they can do it too.  As for the
“style guide.” Be aware that Drupal’s style guide is in contradiction with
most business style guides that I have experience with.

Originally, I argued with and convinced Steven Peck to put the Cookbook as a
top level book where beginners could actually find it. I got many
unsolicited thank you notes as a result. At some point people started
mucking with the organization and the Cookbook has been moved several times
resulting in the people who needed it not being able to find it.

Then handbooks are public property so I cannot stop you from editing it,
even if I had the mind to try. I would ask you, please, to remember that it
is for beginners, not those who already know Drupal well. Frankly, I think
anyone with more than about 9 months of Drupal experience should stay out of
it.

Some feedback:  I see several typos and grammatical errors.  The tone I read
in the first screen of the book is pretty close to exactly what I talked
about above – pedantic and unencouraging. I wrote this book when I was into
Drupal less than 3 months; having succeeded in developing two sites at that
point, I wanted other newbies to see that they too can do it. Don’t
overwhelm them with strict definitions and technical details.

I see what you are trying to do and applaud you for the effort. Now step
back and remember what it felt like to put that first site up. Forget PHP
and Drupal internals – they don’t mean anything to the audience for this
book. They look at most of the stuff on DO and go, “Huh?”  If you don’t
believe that, I’ll try to dig up some of the many emails I got saying that.
Keep it simple, build a little bit at a time. Allow yourself to be a bit
loose with definitions so they are better understood.

Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. - Martin L. King, Jr.

-----Original Message-----
From: documentation-bounces at drupal.org
[mailto:documentation-bounces at drupal.org]On Behalf Of Shai Gluskin
Sent: Monday, March 30, 2009 9:57 PM
To: A list for documentation writers
Subject: [documentation] Some Background/Strategy Help Needed re:
"DrupalCookbook"

Hi gang,

I did some work on the "title" page of the Drupal Cookbook today...

http://drupal.org/handbook/customization/tutorials/beginners-cookbook

I just jumped in, but now I'm seeing some questions I'd like to ask the
group.

The book is written in a very strong "I" voice. Who is it? I couldn't quite
tell from the revisions. I'd respectfully like to tell that person that I'd
like to put some editing work in.

Also, it seems to me like the "I" voice should be removed. That doesn't fit
the style guide and it seems kind of weird, especially since those pages
don't have authors anyway.

Another thing that is weird... the Cookbook is nested under "Beyond the
Basics" but it is also specifically referred to as "For beginners."

If there were plans to retire or replace the "Cookbook" -- I don't want to
waste time. But otherwise, I'd be happy to put some more work into it.

I'd be interested to feedback on the work that I did today on the first
page.
http://drupal.org/handbook/customization/tutorials/beginners-cookbook

I left pretty good notes in the log, and of course you could dif it. I
changed the order of things, mostly took stuff out. The place where I added
the most was in the terms definition section. I think giving some meet there
is helpful, especially for beginners, in lays an important foundation.

Thanks,

shai
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.drupal.org/pipermail/documentation/attachments/20090331/bd1699e8/attachment.htm>
-------------- next part --------------

No virus found in this outgoing message.
Checked by AVG - http://www.avg.com 
Version: 8.0.176 / Virus Database: 270.11.31/2029 - Release Date: 3/29/2009 4:56 PM