[documentation] Hitchhikers guide to Drupal

Thu Jan 5 21:32:57 UTC 2006

Maybe make it a subpage here linking things?
http://drupal.org/node/35172

Additional info on how to contribute
here: http://drupal.org/documentation-writers-guide
here: http://drupal.org/node/24570
here: http://drupal.org/node/339
here: http://drupal.org/about/authoring
here: http://drupal.org/node/10259

Part of the problem, is that many many people are not actually reading the docs.  Just ranting/whining.  Part of the 'tone' of the hitchhikers guide is probably in response to this.  It is getting tiresome.  Some of the posts are making me suspicious as well with virtually duplicate content from few hour old to one week old.  (One user created a new account 'cause' he didn't like the nick on his old one, but refuses to indicate what his old one was and claims over a year in participation).   I have posted many many responses to forum threads on how people can contribute only to be told they're to busy so they won't bother or someone else should just do it.  So many new people seem to be used to the phpBB style where everything is kept in forum posts that are sticky in the forums.  They don't bother even trying to read the handbook.  Only in the last few days have we seen new people respond on this list (which is great, thanks).  

I am re-ordering the handbook currently.  One goal is to consolidate sections so that they make sense and remove duplicate text.  Example;  In the installation and Configuration section, three areas (installing Drupal, installing modules, installing themes) will be consolidated down to one top level (Installing Drupal, Modules and Themes) with a longer introduction and the rest as sub pages.  Installing themes/modules is roughly the same process as installing Drupal itself.  They are all related.  Now, it will have one starting point that overviews and explains it the whole process, then specific sub sections that elaborate  One dedicated to installing Drupal core, one to added new modules and another to themes. Most of this will be done with the existing content.  Where needed, it will be versioned and broken out or unpublished as outdated.  It will need fine tuning later.

With the new handbook versioning, I think that this page http://drupal.org/node/260 needs to go down a level and we can manually copy (or link to the branched version specific version) of the install.txt.  That link is to the CVS version and has lead to much confusion in the past (jump from 4.5 to 4.6)  We also have no instructions on upgrading multisite configurations.  I know how I will do it, but it's a kludge and involes having control of the server.

I am adding brief intro text to each top level section with a note for people to contribute.  A note may not be enough.  Looking at it now on the /handbook page, we have one 'Contributing to Drupal' link (http://drupal.org/node/10259) in the 'Developing for Drupal' section.  It contains how to contribute without coding.

So, what to do besides add blink tags.  
Maybe in the About Drupal section, top level How to contribute to Drupal with an overview of Open Source and links to more specific pages.
In the Installation and Configuration section, How to contribute to installation and configuration
In the Customization and Themeing, How to contribute php snippets/and theming hints
In the Developing for Drupal, clean it up.  The current Contributing to Drupal page/section is one of the older ones and needs to be a bit of refining and updating.
---you get the idea.

Charlie mentioned that he'd been thinking about going over the About Drupal section which it really needs.  However, I don't have the time, nor am I really good at structuring things to 'sell/market' so that is a good place to look at.  Lots of hidden gems in there (like the 

link to my target outline if you missed it: 
http://lists.drupal.org/archives/documentation/2005-12/msg00139.html

-sp

________________________________

From: documentation-bounces at drupal.org on behalf of Bill Fitzgerald
Sent: Thu 1/5/2006 12:11 PM
To: documentation at drupal.org
Subject: Re: [documentation] Hitchhikers guide to Drupal

Hello, all,

Several people have remarked on the tone -- although it didn't strike
me as over
the top on an initial read, after your comments I see can see the error of my
ways :) A few people have remarked on the need to state things positively (ie,
what Drupal is, as opposed to what Drupal isn't) -- that gets abig +1 here.

One of the things this thread seems to reveal is the need for a handbook page
that links to ways non-coders can contribute back to the community.
Most of the
complaints about Drupal's lack of user friendliness come from non-coders. In
some ways, these non-coders are precisely the people we want contributing
documentation on how to use Drupal -- their learning process is fresh in their
minds, and they can see and express the issues new users have better than more
experienced users.

So, toward that end, I will gladly compile and post this list of resources,
tentatively titled "A non-coders guide to contributing to Drupal"

My suggested links:
1. A link to the mailing lists page where they can join the listservs
2. A list of Forums that see a higher percentage of newbie-related questions
(General Discussion, Usability Feedback, Pre-Installation questions,
Installation Problems, How do I style questions)
3. A guide to posting handbook pages (and perhaps a section in the handbook in
close proximity to the site recipes entitled "Tips and Tricks for New Users"?)

Any other suggestions/feedback?

Cheers,

Bill

Quoting "Kim P. Werker" <kim at crochetme.com>:

> On 5-Jan-06, at 10:53 AM, Laura Scott wrote:
>
>> I mean the word in the sense it's used in chess: a kibitzer is 
>> someone who watches and criticizes but doesn't play in the actual 
>> game. Maybe it's too obscure of a reference?
>
> Gotcha. Maybe I'm just too inexperienced a chess player. I forgot 
> about the less benign Yiddish usage -- kibitzing is by its nature 
> pointless (and potentially irritating).
>
> On 5-Jan-06, at 10:55 AM, Boris Mann wrote:
>> Actually, I would say you are the type of person that doesn't need 
>> this notice at all...since you've jumped in and started contributing.
>
> Yes, but I don't know I would have had I read this notice. (I did 
> lots of hand waving and brow-furrowed complaining before I decided 
> that the software is too good to be passed up by people even mildly 
> less stubborn than I am.)
>
> Cheers,
> Kim
> ---
> Editor
> Crochet me Online Magazine
> http://www.crochetme.com
>
> This is your brain on yarn.
>
>
> --
> [ documentation | http://lists.drupal.org/listinfo/documentation ]
>

--
[ documentation | http://lists.drupal.org/listinfo/documentation ]

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20060105/925b18a7/attachment.htm