FreeTDS Development Group

[Norman Palardy <palardyn AT mac.com>]

On Wednesday, October 17, 2001, at 10:37  PM, Brian Bruns wrote:

> Believe it or not, I for one, am genuinely interested in where
> our documentation falls short so it can be fixed.
>
> There are three main pieces:
>
> 1) the INSTALL file with the distribution
>
> It basically says configure, gmake, gmake install and provides some info
> on what the configure switches are for.

It does.
And, I have to confess, that upon rereading it (again) I see what James 
mentioned about dbmfix
I will retry without that option

> 2) The FAQ http://www.freetds.org/faq.html
>
> It contains some common build problems, how to check out of CVS, and 
> other
> FAQs.

I did read all of those; passed over the CVS ones because I figured I 
should be able to get just the version I downloaded to work.

> 3) The FreeTDS Users Guide http://www.freetds.org/userguide/book1.htm

Neither the README nor the INSTALL point you to the User guide
Personally I think this is an oversight

> This is a more ambitious document, explaining how to install, how to
> configure, and how to get several popular packages (SQSH, Perl, PHP,
> iODBC) to work with FreeTDS, along with a trouble shooting section,
> historical information, and how to ask for help on the list if all that
> fails.
>
> So, specifically where was the documentation lacking...were there
> insufficient pointers to the docs? What were you looking for that you
> couldn't find among these three?
Where the heck the user guide was as neither the README nor INSTALL tell 
you where it is, and only a fairly thorough read through the FAQS will 
tell you where it is.

> Looking back on your posts, a couple things come to mind, you never 
> (that
> I could see) mentioned what platform you're using beyond saying you
> attempted to set --host=ppc, so either Mac OS X, Linux PPC, or AIX i'm
> guessing.  There was also no mention of what platform the server is on.
MAC OS X
Servers are on a variety of DEC Alpha's, and Sun Solaris 2.6 through 2.8
They run the gamut from 11.5.1 to 12.x

> The other big thing, as recommended in the troubleshooting section, is 
> to
> set the TDSDUMP env variable and look at the logs.  That will often turn
> up information vital in solving the problem.

I will do that now, but I suspect that the reread of the doc and James 
suggestion has pointed out why my program behaves as it does


> Again, I'm more than happy to fix the documentation if it is deficient 
> in
> some way, but I know FreeTDS inside and out, so it's hard for me to
> objectively look at what's missing.  That's where folks like you are
> supposed to come in.

Personally, I think the best way to package this is to look at it from 
the end consumers point of view.
The person who, like me, really wants to use it (and is perhaps willing 
to pay for the privilege to do so) and perhaps doesn't want to recompile 
it.
I suspect that a huge number of current users already have binaries 
that, packaged properly, could be redistributed at that level

The next is the "Idiots guide to ..." level (perhaps one appropriate for 
me?)
Now maybe that information IS already there, but even reading it through 
and compiling & recompiling with the instructions in hand (literally) it 
sure didn't jump out at me as to what I might be doing wrong and why 
things didn't work