Brian A. Seklecki wrote:

>All:
>
>One of the big things missing from the "Introduction" docs is a more 
>thorough explanation of "How Slony Works".  As a DBA or SysAdmin, that's 
>the first question that I desire to have answered by a manual, and serves 
>to help me better understand all future operations and procedures, 
>especially troubleshooting.
>
>  
>
Thanks, you're one of the first to do any "detailed criticism" of the
docs...

>For example, in introduction.html, it is stated "namely that Slony-I 
>operates using triggers", but what we should probably be saying is:
>
>   "For every table, sequence, or database object that is replicated, Slony 
>is able to replicate changes by installing a trigger that catches updates, 
>inserts, and deletes."
>
>Also, "sl_log" isn't mentioned until Chapter/Page 3 and then again in 7. 
>However, no mention of the "_${repset}_cluster" schema is made at all 
>prior to that point.  It's mentioned in Ch/Pg 5, but the purpose isn't 
>explained.  Somewhere prior mention of "sl_log_1*", there should be a 
>paragraph explaining design:
>
>   "For every database participating in replication, Slony creates a schema 
>named "_${repset}_cluster" at initialization time to maintain 
>configuration and status data.  Most specifically, nodes acting as 
>master/sources maintain a _${repset}_cluster.sl_log_{1,2} table to 
>log/cache of all changes to master which are to be propagated to slaves." 
>(or something to that effect, check me)
>
>  
>
That is in the section on defining clusters, now.

>Also, it's also not explicitly stated anywhere that only Sequences and 
>Tables are replicated.  Although that may seem rudimentary, a it's only 
>briefly touched on.
>
>  
>
That is now explicitly mentioned in several places.

>It should probably be explicitly stated: "A database consists of Casts, 
>Languages, Schemas, Tables, Indexes, Constraints, Sequences, Triggers, 
>Functions, Views, Types, etc.; however Slony only replicates Tables, 
>Indexes, and Sequences.  All other objections constitute DDL changes that 
>must be manually replicated by the administrator." (or something to that 
>effect, check me).
>
>  
>
I am a little reluctant to try to enumerate *all* types of database
objects.  Alan Perlis points out that if you have a procedure with 10
parameters, you probably have missed some :-).  The same is likely true
here.  But I have revised the wording about DDL changes a bit to make it
clearer what is and isn't replicated.

>Another thing to add to the wishlist:  Example real-world scenarios DBAs 
>may encountered and recommended procedures to follow.
>
>  
>
There is a document called "addthings.sgml" to which I have been adding
such of these scenarios as seem to come along.

Beefing it up with "recipes" for how to do additional things is
certainly fair game.

>Also, it wouldn't hurt to break out XFig or Dia and add some explanatory 
>diagrams explaining concepts.
>  
>
I'm not much of a graphical person, which is why the paucity of diagrams...

>Thoughts?
>
>(And yes, I'm will to help write docs!) >:}
>  
>
Now that I've changed these things, it looks like I need to do a bit of
fiddling with the "man page" version :-(.  Task for tomorrow...

I have not yet checked all the changes in; I want to make sure I can
cleanly run nsgmls on both slony.sgml and man.sgml (having some troubles
at the moment).  It'll go in tomorrow.