DBD::Oracle Documentation clean-up

[Yanick Champoux]

Hi all,

Just to say that with regard to RT-72252 (main DBD::Oracle POD went
ashtray after v1.28), I've spend the day trying to organize the main pod
of DBD::Oracle to be a little cleaner and follow a more logic flow.

I've merged my changed with the master on
https://github.com/yanick/DBD-Oracle If anyone feel like checkin it out
and verifying that my rejuggling of the doc makes sense, it'd be
appreciated.

Joy,
`/anick
--
Pythian proud winner of Oracle North America Titan Award for Exadata Solution...watch the video on pythian.com

[Gwen Shapira]

I like the re-org.

Getting all the connectivity issues and details out of the DBD::Oracle
POD and the readme and move it into DBD::Oracle::Troubleshooting is a
great improvement. The content itself is still a problem, but most of
it is known issues and can be improved gradually.

However, it does look like you added the following line:
"It is best to not use ORACLE_SID or TWO_TASK as both of these are
rather out of date."
AFAIK, ORACLE_SID is not out of date and is very commonly used.

I agree that it is often better not to use environment variables for
connectivity as they tend to make debugging more challenging, but I
also think that DBD::Oracle POD is not the right place for debugging
best practices. We have blogs for that ;)

Nit-picking-ly yours,
Gwen

P.S this entire email is just an excuse to show off the fact that I
finally managed to "pull" the git repository and see the latest and
greatest. Now I just need to figure out the whole branching and
merging thing so I can contribute too.

[Gwen Shapira]

One more note:

The examples for using Long datatype are now in
DBD::Oracle::Troubleshooting. All other examples are still in
DBD::Oracle. I find this confusing.
Maybe we need DBD::Oracle::Examples? Or just move the long datatype
examples back.

Gwen

[Jared Still]

On Thu, Nov 10, 2011 at 3:28 PM, Gwen Shapira <sha...@pythian.com> wrote:

However, it does look like you added the following line:
"It is best to not use ORACLE_SID or TWO_TASK as both of these are
rather out of date."
AFAIK, ORACLE_SID is not out of date and is very commonly used.

Ageed, ORACLE_SID is very much in-date.

And I believe TWO_TASK is still used in Oracle Apps environments.

 

P.S this entire email is just an excuse to show off the fact that I
finally managed to "pull" the git repository and see the latest and
greatest. Now I just need to figure out the whole branching and
merging thing so I can contribute too.

Got the git going - just need more time.

[Yanick Champoux]

On 11/10/11 18:28, Gwen Shapira wrote:
> I like the re-org.

\o/

>
> Getting all the connectivity issues and details out of the DBD::Oracle
> POD and the readme and move it into DBD::Oracle::Troubleshooting is a
> great improvement. The content itself is still a problem, but most of
> it is known issues and can be improved gradually.

Yup. My thoughts exactly. As I'm still an Oracle noob, I can only
superficially edit the content, so for the time being I'm focusing on at
least shaping it in a way that is easier to navigate, secretly hoping
that brave documentation fairies will emerge from the woodwork and help
with the factual information itself at some point. :-)

>
> However, it does look like you added the following line:
> "It is best to not use ORACLE_SID or TWO_TASK as both of these are
> rather out of date."
> AFAIK, ORACLE_SID is not out of date and is very commonly used.

Didn't add it as much as percolated it from a deeper section of the
doc. Do you think you could provide me with a better phrasing for that
section? <eyes mode="puppy"> Pweeease? </eyes>

>
> I agree that it is often better not to use environment variables for
> connectivity as they tend to make debugging more challenging, but I
> also think that DBD::Oracle POD is not the right place for debugging
> best practices. We have blogs for that ;)

Agreed. Or, alternatively, DBD::Oracle::Don't::Do::That :-)

>
> P.S this entire email is just an excuse to show off the fact that I
> finally managed to "pull" the git repository and see the latest and
> greatest.

Sweet. Congrats! *\o/*

> Now I just need to figure out the whole branching and
> merging thing so I can contribute too.

I'll try to round up a couple of good tutorials and screencasts,
which might help.

Trust me, right now you hate me. But in the long run? You'll
celebrate the day you stepped into the world of DVCSs. :-)

[Yanick Champoux]

All right, we're beginning to cook some serious gumbo, here! :-)

I've merged back your edits in my master, Gwen. Thanks!