From stumbling through the docs on CVS, module development, and project submission for over a day I think the docs could benefit from an Encyclopedia of definitions. Just joining the module developer realm (and never having used a CVS) I was very confused by some terms and had to trial and error my way into them. I also find that I'm explaining common drupal concepts to people that I train in drupal at work. Instead of explaining these concepts to people every time I think it would be good to centralize them as well as state what version of Drupal they are used in. Example: A node is the most basic form of all user submissions in Drupal. Think of node as an object. An Object can take on many forms such as a "page" or "story". A Page Object has a title and a body.

This is a fairly simple idea but centralizing a lot of terms and concepts that are common to people getting into Drupal could really jump start people's entry into the community. Drupalcon Boston seemed to focus on a lot of usability issues and the point of usability is to lower the cost of entry. The happier we make user's first experience with Drupal the more likely they are to adopt it. The more times someone has difficulty with a term and they have a highly visible place to come and figure out what that means instead of constantly defining terms on #drupal to newbees and experts alike.

Concepts / terms could have a short definition with links off to several related articles. A lot of experts tracked down module submission documents for me in seconds but it took me hours to figure out where they were my first time through and left me very frustrated! I have no problem starting this initiative if other people think it's a good idea...

I think this should also be separate from all the different guides and provided references into all of them.

Comments

add1sun’s picture

add1sun commented

We do have a list of basic Drupalisms in the Terminology section of the Getting Started Overview (http://drupal.org/node/937). We have terminology that is pertinent to specific spheres and perhaps needs to be explained slightly different ways for people coming at it differently (r.g. a node as my content for an end user vs node as an object for a developer.) So we need to think out how we want to organize this info if we expand beyond the basic ideas we already have outlined. I do think we can use some work on addressing this as well as generally making things more findable. Please join the discussion about the redesign on d.o as well since the documentation will be a big part of that and we have some discussions going on. There is also a larger meta discussion happening right now in the docs team about reorganizing the About Drupal section and creating a new contributors guide kind of handbook.

Initial thread: http://lists.drupal.org/pipermail/documentation/2008-March/005874.html
Summary of last meeting: http://lists.drupal.org/pipermail/documentation/2008-March/005924.html
Next IRC meeting to discuss: http://lists.drupal.org/pipermail/documentation/2008-March/005926.html

Anonymous’s picture

Anonymous (not verified) commented
Component: Misc » Other documentation issues
Status: Active » Closed (fixed)
awelch’s picture

awelch commented

I think this is a great idea. Having clear definitions of the concepts making it a lot easier to understand and adopt Drupal.
I've come from a Wordpress background on the one hand and an ASP.net VB.net background on the other. Wordpress is focussed on the post / page objects and It's a very simple jump to understand these as nodes instead, but something which perhaps provides a barrier at first.

I'm coming at it from the point of view of a developer and I don't think it makes a lot of difference if I called a node an object or content, but it makes more sense to me to call it an object because it could be anything whereas content implies text, images, and other 'content' in the traditional sense of the word.

Thanks

Andy (welchcreative.co.uk)