[documentation] [Documentation task] pls review my drupal db docs

Wed Jun 28 21:45:19 UTC 2006

Issue status update for 
http://drupal.org/node/70825
Post a follow up: 
http://drupal.org/project/comments/add/70825

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  sime
 Updated by:   sime
 Status:       active

@Max Bell
Hopefully my description of boxes is correct! Time will tell.  :-)

sime

Previous comments:
------------------------------------------------------------------------

Mon, 26 Jun 2006 07:47:57 +0000 : sime

A little time ago, I was doing my first multi-site installation and I
was trying to work out which tables should be shared between the
different sites. 

What I needed was a simple description about the purpose of each table.
What I found was this ticket:
http://drupal.org/node/28046
and this book page:
http://drupal.org/node/38977

This is good effort towards a proper data dictionary, which is going to
take a fair bit of work. In the meantime, I decided that a much simpler
summary was enough to get a brief overview of what the tables are used
for. And something that would help a lot of people in the short term.

So I have created some pages which give an overview of the standard
tables in Drupal. They are grouped according to their usage. My target
audience have limited experience with "keys", "querys" and
"relationships", so I largely overlooked these concepts - although
you'll see in each diagram, that I do hint at relationships between
tables, albeit in a way that doesn't alienate newbies.

These are all in the moderation queue of course. However, I'd love it
if these pages were reviewed as a whole. With an additional request to
place them in (more-or-less) the order outlined below.

http://drupal.org/node/22754 - parent page

http://drupal.org/node/70516 - user tables
http://drupal.org/node/70591 - node tables
http://drupal.org/node/70605 - node type tables
http://drupal.org/node/70614 - taxonomy tables
http://drupal.org/node/70623 - search tables
http://drupal.org/node/70625 - layout & nav tables
http://drupal.org/node/70627 - localization tables
http://drupal.org/node/70624 - RSS tables
http://drupal.org/node/70791 - tracking tables
http://drupal.org/node/70796 - system tables
http://drupal.org/node/70814 - other tables

I look foward to a review.
Simon

------------------------------------------------------------------------

Tue, 27 Jun 2006 06:55:35 +0000 : killes at www.drop.org

Cool stuff!

the description of the node table looks wrong to me.

published the user page

term_data
A term is a label that can be applied to things. This table is where
the terms are defined.

s/things/nodes/

locale_target
    Translated content.

translated strings. (corrected and published)

I am wondering why we woul dneed a pupup-link on the (very nice)
graphics, they are shown fullsize anyway.

I am also wondering what non-technical users might want to do with the
info. ;)

------------------------------------------------------------------------

Tue, 27 Jun 2006 07:17:04 +0000 : sime

killes, thanks for looking!

I will do those changes. But firstly your last 2 general comments.

*Pop-up link on graphics?*

Not important. I thought if a person has a small screen, they might be
inconvenienced. (Of course, in firefox I can just right click->view
image.)  If you think I should change this, I will.

*What would non-technical users do with it?*

To rephrase myself: "this lowers the barriers for new coders".

I am targetting people who are learning how to code (or learning how to
code for Drupal). Drupal can be intimidating when you start, and it can
be exhausting when every step is a giant one. Having documents like
this allows newbies to look up tables in a superficial way (no brain
power wasted).

------------------------------------------------------------------------

Tue, 27 Jun 2006 19:45:50 +0000 : rivena

As just an additional thought, one more way to explain is to take a set
of sample data, and show where each bit of information goes.

For example, user 5, Joe Drupal, language: French, etc, etc.  

You have to be careful to not make it any more confusing by doing this,
but it might be useful.  :)  Maybe a sub page?

Anisa.

------------------------------------------------------------------------

Wed, 28 Jun 2006 00:20:57 +0000 : sime

This is a good idea. I also like the idea of having a sample query as
they appear in drupal and explain what it is doing.

It took quite a while to look through the code to find out how some of
the tables were being used. And in the end, just making sure that all
tables had a simple explanation was a challenge to complete.

So to start, I'll work through killes suggestions to get these
published. Then some value-adding might follow.

Thanks for the feedback.

------------------------------------------------------------------------

Wed, 28 Jun 2006 01:58:40 +0000 : sime

@killes
I have fixed up the link issues and the description for node.

I have also enhanced the diagrams so that they show where one-to-many
relationships exist. However I don't want to make a big deal about it,
because some people will not know what that is.

------------------------------------------------------------------------

Wed, 28 Jun 2006 09:30:42 +0000 : balasatya

Sime,
You have done an excellent job. I know the agony of newbie’s in
Understanding Drupal Innards. It would be more helpful if any one add
appropriate module code snippets along with database schema to
understand the Drupal core API.
Thanks for your great work.
(Sorry for posting it in other node)

------------------------------------------------------------------------

Wed, 28 Jun 2006 10:33:02 +0000 : Max Bell

What I'd point out is that while I've had a /little/ exposure to these,
there is no particular reason why I would have understood them. That
said, I didn't have any trouble understanding them at all. I was
surprised to learn that "boxes" are an alternate term for "user defined
blocks", which, for some reason, I thought related to things like
messages...