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

Fri Jul 7 01:17:44 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

Thanks for the excellent feedback. If you'd like to send me raw html I
will look at it. Essentially I'll gone with mark-up simplicity to start
with, I really don't like the
 styling on drupal.org.

Putting the list in a table is a fair call. I might let the page mature
a bit and see what other columns would be useful first. I'm a bit "think
first, act later" kind of guy. :-)

Re fonts: you think I should change the font in the images to match the
font of the page? I am not very font canny, but I'll have a go at that
the next time I need to update the images.

As for "UML diagrams" and "layout conventions", I don't intend to do
that because these pages are supposed to be accessible to new coders
who just want to know what a table is for, or which table stores xyz.  
 A child page called "UML schema" or something would be good - but I
personally don't intend to do this as it would be duplicating a work in
progress [1].
[1] http://drupal.org/node/28046

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...

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

Wed, 28 Jun 2006 21:45:19 +0000 : sime

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

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

Fri, 07 Jul 2006 00:33:07 +0000 : Gary Feldman

I'm not sure whether this comment belongs here or as a comment on one of
the pages in question, but when I look at these pages (e.g.
http://drupal.org/node/70625), I have no idea what I'm looking at.

I don't think this is entirely your fault, but rather that the
available HTML here doesn't let you do tables, and discourages
headings.  There's also no obvious pattern of font usage, and much of
the font usage is non-standard, so the boldface doesn't help.  

The list of database tables is crying out for a real HTML table (no pun
intended).  There should be headers saying "Table Name" and
"Description".  Barring that, you might say in prose "Below is a list
of table names, and a description for each one."  I'd also suggest
changing the table names from boldface to italics.  The picture (at
least on this page) just duplicates the prose, and doesn't seem to add
anything, so I'd leave it out.  For those tables that have
relationships, I'd just show the relevant UML diagrams, preferably done
with something that uses standard conventions.  (I don't have any
suggstions for a tool, but there ought to be some freeware out there.)

Or maybe it should be something like:

"
Here are the tables relating to layout:

* blocks
* boxes
* menu
* url_alias

The blocks table
Each type of block has a record containing its weight, region, etc.

"
Gary

PS: OK, I lied.  I was able to figure out what I was looking at.  But
what I said above was my first reaction.  The transition from the
opening paragraph to the list of tables is jarring.  I first thought
the word "blocks" might be introducing a category of database tables
related to blocks, with "Block configuration settings" the description
of the category, and "theme, status, region, ..." being a list of the
actual tables related to blocks.    

PPS: It should be /affects/, not /effects/.

PPPS: Getting the above sample to look halfway like it should is part
of the problem I was trying to describe in the first paragraph.  I
can't find a way to show something indented without being forced to
italics and having those stupid quote mark graphics added.  But then,
I'm ranting about the style again.