[drupal-docs] Moving handbook to docs.drupal.org

Kieran Lal kieran at civicspacelabs.org
Fri Mar 18 00:02:18 UTC 2005


On Mar 17, 2005, at 3:31 PM, Anisa wrote:

>
>  I am also not entirely sure on this.  What are the difficulties in 
> improving the handbook?
I think one of the difficulties is we need some room to change the 
drupal documentation experience.   Ideally this documentation shouldn't 
rest on drupal.org or docs.drupal.org but it should be a Drupal Core 
module that ships with every site.   I got a phone call this morning 
from a woman who was trying to put up a site for dog owners to get 
involved in local politics.  She had been to Bryght, CivicSpace, and 
Drupal already that morning.   She started describing her experience 
trying to understand how to get information on the Drupal site.  She 
started screaming hilarious descriptions of how awfully geeky the site 
was.  I was laughing so hard hearing her descriptions of the 
information being presented to her.  I told her I wanted to get a 
recording so I could share it with all of you.  These are the new users 
of Drupal, like it or not.

Drupal.org is fine the way it is.  It has a particular audience and it 
meets their needs.  But if we want it to be more accessible, and I do, 
we need some room to create a learnable, exploratory documentation site 
where novices can tread without fear.

I am currently looking at the Drupal workbook and it presents me with 
close to 50 links.  That is undigestible for most people.   I could go 
on about information architecture, semantic loading, and understanding 
your users situation and expectations.  But we need a blank canvas to 
take a fresh approach.   If it's not on drupal.org for a little while I 
am fine with that.  If the drupal community wants it there then I am 
fine with that too.

I am not sure we actually need or want developers writing the next 
generation of Drupal documentation.   Of course developers will always 
make a necessary contribution.

Anisa, I don't know if you are a developer but your constant stream of 
taking obscurity to task is incredibly refreshing.  I think with a 
fresh start we can get more people doing documentation.  The CivicSpace 
community certainly has no shortage of bloggers we can recruit.  I have 
also had several professional usability experts approach CivicSpace and 
these people are fans of and use Drupal.  But they find it too 
intimidating to contribute. I think a documentation site with a new 
experience could attract more people to this effort.

Cheers,
Kieran



>   Whatever you do, you have to re-write it over again...  why does 
> moving it help?
>
>  If you believe there advantages to having a site entirely focused on 
> supporting people using drupal, that's one thing. 
>
>  Hm.  Unless you mean that moving it will force people to rewrite 
> everything instead of just letting it be?  :)  There's a thought.  I 
> wonder how many developers will help out at the new site though. 
>
>  Anisa.
>
>  Boris Mann wrote:
> On Thu, 17 Mar 2005 08:06:50 +0100, Dries Buytaert 
> <dries at buytaert.net>  wrote:
>
>
> Are we sure the 'pros' are worth it?  Admittedly, I'm not really
> convinced they are.  I wonder what problems we are solving.
>
> My question: what are the _problems_ we are trying to solve, and how
> does moving the handbook help?
>
> Without a "clean slate", it will be very, very difficult to bring
> documenbtation to an acceptable level.
>
> Already external documentation on Bryght, CS, and DevSeed is much,
> much better at answering people's questions and solving their problems
> than the handbook is. With the current state of the handbook, the
> information from those three sources would be very difficult if not
> impossible to integrate.
>
> Much like we have not been afraid to change code/APIs if it makes
> things better for Drupal code, I believe we need to do the same with
> the Drupal handbook.
>
> Shane has done a good job of explaining -- this is not an all or
> nothing, but rather a kind of "best of" where we have a place to make
> a fresh start. My list of pros and cons were by no means complete --
> rather meant to start discussion, which is what we're having.
>
> --
> Boris Mann
>  http://www.bryght.com
>
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: text/enriched
Size: 4315 bytes
Desc: not available
Url : http://drupal3.drupal.org/pipermail/documentation/attachments/20050318/33f488bd/attachment.bin


More information about the drupal-docs mailing list