Nancy and documenters,<br><br>Nancy, nice to meet you! And great work on the Cook Book.<br><br>I really think we are on the same page. I put back some of the encouragement language.<br><br>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.<br>
<br>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.<br>
<br>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.<br><br><blockquote>
"Forget PHP and Drupal internals – they don’t mean anything to the audience for this book."<br></blockquote><br>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.<br>
<br>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.<br>
<br>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.<br>
<br>But as I said, I really think we are much more on the same page than you might think.<br><br>best,<br><br>Shai<br><br>2009/3/31 Nancy Wichmann <<a href="mailto:nan_wich@bellsouth.net">nan_wich@bellsouth.net</a>><br>
><br>> 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.<br>
><br>> <br>><br>> 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.<br>
><br>> <br>><br>> 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.<br>
><br>> <br>><br>> 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.<br>
><br>> <br>><br>> 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.<br>
><br>> <br>><br>> Nancy E. Wichmann, PMP<br>><br>> Injustice anywhere is a threat to justice everywhere. - Martin L. King, Jr.<br>><br>> <br>><br>> -----Original Message-----<br>> From: <a href="mailto:documentation-bounces@drupal.org">documentation-bounces@drupal.org</a> [mailto:<a href="mailto:documentation-bounces@drupal.org">documentation-bounces@drupal.org</a>]On Behalf Of Shai Gluskin<br>
> Sent: Monday, March 30, 2009 9:57 PM<br>> To: A list for documentation writers<br>> Subject: [documentation] Some Background/Strategy Help Needed re: "DrupalCookbook"<br>><br>> <br>><br>> Hi gang,<br>
><br>> I did some work on the "title" page of the Drupal Cookbook today...<br>><br>> <a href="http://drupal.org/handbook/customization/tutorials/beginners-cookbook">http://drupal.org/handbook/customization/tutorials/beginners-cookbook</a><br>
><br>> I just jumped in, but now I'm seeing some questions I'd like to ask the group.<br>><br>> 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.<br>
><br>> 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.<br>><br>> Another thing that is weird... the Cookbook is nested under "Beyond the Basics" but it is also specifically referred to as "For beginners."<br>
><br>> 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.<br>><br>> I'd be interested to feedback on the work that I did today on the first page.<br>
> <a href="http://drupal.org/handbook/customization/tutorials/beginners-cookbook">http://drupal.org/handbook/customization/tutorials/beginners-cookbook</a><br>><br>> 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.<br>
><br>> Thanks,<br>><br>> shai<br>><br>> No virus found in this outgoing message.<br>> Checked by AVG - <a href="http://www.avg.com">http://www.avg.com</a><br>> Version: 8.0.176 / Virus Database: 270.11.31/2029 - Release Date: 3/29/2009 4:56 PM<br>
><br>> --<br>> Pending work: <a href="http://drupal.org/project/issues/documentation/">http://drupal.org/project/issues/documentation/</a><br>> List archives: <a href="http://lists.drupal.org/pipermail/documentation/">http://lists.drupal.org/pipermail/documentation/</a><br>
<br>