On Wed, Jul 12, 2006 at 09:20:59PM +0000, Christopher Browne wrote:
> elein wrote:
> > On Wed, Jul 12, 2006 at 08:30:51PM +0000, Christopher Browne wrote:
> >   
> >> Brad Nicholson wrote:
> >>     
> >>> Christopher Browne wrote:
> >>>
> >>>   
> >>>       
> >>>> * There is interest in the perl tools to keep a buffer for the general
> >>>> community between admin and the guts of Slony.
> >>>>
> >>>> (cbb: Is there interest in *working on* the Perl tools? As an OSS
> >>>> project, there is a need for volunteers. In the case of the Perl tools,
> >>>> past volunteers have stepped away, so we kind of need new ones...)
> >>>>     
> >>>>         
> >>> Was there any discussion as to what area the perl tools were lacking in?
> >>>   
> >>>       
> >
> > Yes.  I added my two bits regarding that they must be properly maintained
> > and better documented.
> >
> > I am considering writing the howto for slony administration using the
> > processes I use for perltools.   These would be task oriented rather
> > than the nuts and bolts documentation required by the development
> > team.  There is no "dba off the streets" level of documentation, imho,
> > except the little I've written so far.
> >
> > Should I take this on as a pgfoundry project or just rework the 
> > how to documents?  I don't want to step on toes or to eliminate the
> > nuts and bolts documentation we already have.
> >   
> There is a section with a "task orientation"; we started by constructing
> a list of "seemingly interesting" tasks on the Wiki
> <http://slony-wiki.dbitech.ca/index.php/Howto>, and I took the results,
> extended them, and put that into the admin guide; see the CVS pointer
> <http://gborg.postgresql.org/cgi-bin/cvsweb.cgi/slony1-engine/doc/adminguide/addthings.sgml?rev=1.17;content-type=text%2Fplain;cvsroot=slony1;only_with_tag=HEAD>
> 
> It would seem to me that extending that would make the documentation set
> more complete, and the ability to interlink inside the one document
> seems valuable too.
> 
> There is certainly benefit in adding material there; you can link to the
> Slonik reference guide (the existing material points to the manual pages
> pretty extensively), as well as to material elsewhere.  The material I
> put in didn't make reference to any of the altperl tools, but you'd
> certainly be able to <xref> to them, which would make it more valuable
> to beef up the altperl documentation as well...

The point of what I could write is that it is from the dba on the street
perpective, rather than the slony task perspective.  You are working, as you
should be, on a slony task level.  The higher level would be more like:  Why do you want
a replica?  A recommended environment set up technique which uses perltools. 
How to fix your db so it has PKs and UI and why. What is failover (as opposed
to move set)?  These are off the top of my head. But I go over each step carefully
with every client that I've set up slony.  

At some point, many of my clients get down to the level of the slony documentation
but certainly not all of them.  But in order to get there, the non-trivial
understanding and set up needs to be covered in a language that they understand.

So this will not be in the same style at all as what is there already.  But I like
the idea of being able to cross reference.  Perhaps a large addendum tutorial document
would be appropriate instead of changing the existing work?

BTW I have accidently found myself on the wiki for the howto several times,  Shouldn't
the link be more prominent?  I would need cvs privileges in order to change
the sgml, but it may be possible to funnel that through fetter or some other committer.

I'd like to hear concerns about too many documentation branches as well as 
real life problems that people have run into when setting up and administering slony.

--elein
elein at varlena.com


> _______________________________________________
> Slony1-general mailing list
> Slony1-general at gborg.postgresql.org
> http://gborg.postgresql.org/mailman/listinfo/slony1-general
>