[documentation] Adding an introductory overview to the Handbook, under Installation and configuration (repost)

Benjamin Slade ben at benslade.com
Mon Jan 30 13:26:42 UTC 2006


(I'm reposting this message as plain text.  Apologies for the previous 
HTML version)

I'd like to submit the following suggestion for introductory 
documentation to be added to the Installation and configuration handbook 
under the first section, "Introduction to Drupal terminology".

I'm suggesting changing the 1st paragraph on this page from:

Drupal is a web-based content management system. Text and pointers to 
other kinds of content are stored in a database, dynamically retrieved 
and composed, and presented to a user in response to a request sent via 
a web-browser.

to:

 Drupal is a web-based content management system.   Text and pointers to 
other kinds of content are stored in a database, dynamically retrieved 
and composed, and presented to a user in response to a request sent via 
a web-browser.

 Content in Drupal is created in individual "nodes".    For nodes of 
type "story", users can add comments to the node (comments themselves 
are not considered nodes).   Depending on site settings,  adding new 
nodes and/or posting comments might or might not be allowed.   Also, 
nodes or comments might require approval from the moderators before the 
node or comment is displayed.   Blog entries are another type of Drupal 
node.

 The default Drupal layout ("Theme"), consists of three columns.   The 
center column is referred to as the "Content Column".   It typically 
displays summaries of the most recently posted nodes in date order.   If 
you click on a node summary, the full content of the node is displayed 
in the center column.

 The left and right side columns are referred to as the sidebars.    The 
side bars can display "blocks" of related information.  Blocks often 
contain links for navigating to other nodes.   For example, there can be 
blocks displaying the most recently posted stories, or the most popular 
stories.  For new installations, the login block displays, along with a 
navigation block containing a menu of available actions.   Different 
menu items can display in the navigation block depending on what you're 
doing and what privileges ("roles") you have.

 Blocks may or may not display depending on what you're doing and what 
privileges ("roles") you have.  For example, the login block will not 
display if you're already logged in,  or the "most recent stories" block 
may not display if there are no story nodes available.   The 
administrator can enable/disable different blocks under the 
Admin->Blocks menu item.

 Nodes can be organized into categories, also called taxonomies.    
Forums are an example of content nodes organized by category.  
Categories can be hierarchical, where one parent category contains 
multiple child categories.

 New features in Drupal are often implemented as "modules".    Once an 
administrator adds a module file to the "modules" subdirectory, the 
option to use the module appears in the Admin->Modules section.   If the 
administrator enables that module in Admin->Modules, the features 
associated with that module become active.   A module may define new 
node types, new menu items may appear in the navigation block, and new 
types of blocks may become available for display in the sidebars.

# end of suggested doc update

It took me months to figure out the above information.   I wish this 
intro had been there for me.

Granted, this text is a little redundant with the terminology section, 
but it's presented in conceptual order (presenting the base concepts 
first) rather than alphabetical order.   I feel this is extremely 
important for a new reader.  The terminology section is better for 
reference, not introduction.

All feedback appreciated.

Ben Slade
Washington DC
"Beer is proof that God loves us and wants us to be happy" (Benjamin 
Franklin)


More information about the documentation mailing list