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

[Shai Gluskin]

Nancy and documenters,

Nancy, nice to meet you! And great work on the Cook Book.

I really think we are on the same page. I put back some of the encouragement
language.

I think maybe the answer to some of the "I" language stuff and maybe the
volume of encouraging language is that the PDF should be different from the
web version. I have no intention of changing the PDF version. I think on the
web the "I" is just simply confusing, especially when an author isn't even
referenced anywhere but in the revisions tab.

As for the web version, I just think the pages should be shorter because
people don't read long pages on the web. Actually, I've really only looked
at the first page, so maybe the other pages are short. But the first page is
very long.

I have no interest in making it more technical at all. I took out the
reference to Windows precisely because it was a technical issue and it was
off-topic as well! You likely didn't even put that there.

"Forget PHP and Drupal internals – they don’t mean anything to the audience
for this book."


I didn't write anything about PHP or Drupal internals. I see a reference to
PHP in the section about what to do on Drupal.org... which is way too long.
Likely you didn't put that there, and neither did I. What I did was simply
give them the path to find their PHP version and MySQL version numbers so
they aren't completely frustrated should they follow that suggestion. I
would be fine with that whole bullet coming out.

Nancy, I really think we are on the same page and that someone came in
between your edits and mine who made things more technical and/or long and
confusing. You'd really have to run the diff between two days ago version
and now to see precisely what I did.

The only parts I lengthened were the node definition and the block
definitions. And I don't think I added technical language. In the menu
definition I added that these menus are available to place in the display
via block admin. Pointing that out helps people past a huge frustration that
many face. I think what people want to know is... "how do I get control of
something to put it somewhere." That was the focus of my attention. It was a
huge aha for me when I realized that some blocks are built by modules and
other blocks you can make yourself, but both are controlled via the block
admin menu. Those are really confusing stumbling blocks that I think can be
overcome as part of a basic description, and that is why I added them.

But as I said, I really think we are much more on the same page than you
might think.

best,

Shai

2009/3/31 Nancy Wichmann <nan_wich at bellsouth.net>
>
> 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
>
> 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
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.drupal.org/pipermail/documentation/attachments/20090331/6fc4533c/attachment-0001.htm>