What Is Up With Oracle Documentaion?

[Steve]

I never liked Sun's documentation of java/java technology. I am
longing for it now that Oracle has obtained Java and is begining to put
its own documentation on the web.

I can't articulate exactly how, but their documentation style almost
seems to be intentionally obfuscating the subject they are discussing.

It isn't just using high level terms without defining them, everyone
does that. The reader just has to suck it up and look up the meaning of
the terms.

It seems like the oracle documentation only gives short tidbits of text
that explain things only in general terms without tying it into the
"whole story" for figuring how to do something?

LOL? Do you think it is an intentional move to have people pay to go to
special classes and then have others pay those gradutes?

Is there anything people can do beyond just making sure they fully
understand each word they read before reading further?

[Roedy Green]

On Tue, 24 Apr 2012 10:20:24 -0400, Steve <tink...@gmail.com> wrote,
quoted or indirectly quoted someone who said :

>I never liked Sun's documentation of java/java technology. I am
>longing for it now that Oracle has obtained Java and is begining to put
>its own documentation on the web.

I very rarely find documentation that I like. So I spend a fair bit
of time writing my own.

And, I don't like my own either, because so often it is just a
disconnected chain of tidbits, lacking overall structure, and of
course it goes out of date as soon as I hit enter.

I update it piecemeal, which creates some strange syntax. When it
gets too disgusting, I read the piece as a whole and try to make sure
all is consistent and organised. This is incredibly time consuming.

I don't try to be comprehensive, just say the most important things
that someone starting out needs to know to give an overview. I figure
once they have the lay of the land they can make sense of the official
docs to get the details.
--
Roedy Green Canadian Mind Products
http://mindprod.com
When you were a child, if you did your own experiment
to see if it was better to put to cocoa into your cup first
or the hot milk first, then you likely have the programmer gene..

[gra...@gmail.com]

On Tuesday, April 24, 2012 7:20:24 AM UTC-7, Steve wrote:

> LOL? Do you think it is an intentional move to have people pay to go to
> special classes and then have others pay those gradutes?

That is what Netware did. As soon as they announced that they were going to focus on profiting from consulting services, all their documentation went down the tubes. Document A would give a little hint and refer you to Document B, which would give you a little hint and refer to Document Q, which would give you a little hint and refer you to Document S, which would say the same thing as Document A but refer you to Document M, which would give you a little hint and refer you to document A. That was my first clue to get out of the IT industry unless I wanted to spend the rest of my life beating my head against server-room walls.