Re: Venting about docs

#1

Art S. Kagel wrote:

Quote:

Since this is shaping up to be a slow posting day, I want to take the
opportunity to vent.

For years Informix had award winning documentation and, while it took me
a while to get used to them when they first showed up in the OL4.01 or
OL5 docs, the railroad syntax diagrams were actually easy to read and
follow. The original PDFs, whether you like PDFs or not (and I do), were
easy enough to navigate with hot links in expected places. So, why were
the docs for IDS 9.40 and IDS 10.00 changed to those hairy pseudo
railroad diagrams with the footnote pointers to get to hot links? The
PDF files are now VERY difficult to navigate and the changes did not
make the HTML versions any better.

I want my old docs back! Just my opinion.

Anyone else got one on this topic? It's got to be better than "Is DB2
dead?" or whatever that thread has morphed into.

Art S. Kagel

I totally agree with you.
I'd love to move my customer to 10.00 but I fear the day when I must
browse those books... Besides being a PITA to use they're even much
uglier

#2

Fernando Nunes wrote:

Quote:

Art S. Kagel wrote:

Since this is shaping up to be a slow posting day, I want to take the
opportunity to vent.

For years Informix had award winning documentation and, while it took
me a while to get used to them when they first showed up in the OL4.01
or OL5 docs, the railroad syntax diagrams were actually easy to read
and follow. The original PDFs, whether you like PDFs or not (and I
do), were easy enough to navigate with hot links in expected places.
So, why were the docs for IDS 9.40 and IDS 10.00 changed to those
hairy pseudo railroad diagrams with the footnote pointers to get to
hot links? The PDF files are now VERY difficult to navigate and the
changes did not make the HTML versions any better.

I want my old docs back! Just my opinion.

Anyone else got one on this topic? It's got to be better than "Is DB2
dead?" or whatever that thread has morphed into.

Art S. Kagel

I totally agree with you.
I'd love to move my customer to 10.00 but I fear the day when I must
browse those books... Besides being a PITA to use they're even much
uglier

If it's any consolation, I think the Tech Pubs (ID - Information
Development) people would agree - and the absence of the index letters
at the top of the index pages is a nuisance too.

However, the reason for the change is so that the manuals can be handled
by automatic systems for the visually impaired - accessibility is the
jargon usually used. The railroad diagrams can, apparently, be handled
better than the much finer ones that used to be in the Informix manuals.

IBM does a lot of work with the US federal government, and such things
are important to contracts with it.

--
Jonathan Leffler #include <disclaimer.h>
Email: jleffler (AT) earthlink (DOT) net, jleffler (AT) us (DOT) ibm.com
Guardian of DBD::Informix v2005.01 -- http://dbi.perl.org/

#3

Jonathan Leffler wrote:

Quote:

Fernando Nunes wrote:

Art S. Kagel wrote:

Since this is shaping up to be a slow posting day, I want to take the
opportunity to vent.

For years Informix had award winning documentation and, while it took
me a while to get used to them when they first showed up in the
OL4.01 or OL5 docs, the railroad syntax diagrams were actually easy
to read and follow. The original PDFs, whether you like PDFs or not
(and I do), were easy enough to navigate with hot links in expected
places. So, why were the docs for IDS 9.40 and IDS 10.00 changed to
those hairy pseudo railroad diagrams with the footnote pointers to
get to hot links? The PDF files are now VERY difficult to navigate
and the changes did not make the HTML versions any better.

I want my old docs back! Just my opinion.

Anyone else got one on this topic? It's got to be better than "Is
DB2 dead?" or whatever that thread has morphed into.

Art S. Kagel

I totally agree with you.
I'd love to move my customer to 10.00 but I fear the day when I must
browse those books... Besides being a PITA to use they're even much
uglier

If it's any consolation, I think the Tech Pubs (ID - Information
Development) people would agree - and the absence of the index letters
at the top of the index pages is a nuisance too.

However, the reason for the change is so that the manuals can be handled
by automatic systems for the visually impaired - accessibility is the
jargon usually used. The railroad diagrams can, apparently, be handled
better than the much finer ones that used to be in the Informix manuals.

IBM does a lot of work with the US federal government, and such things
are important to contracts with it.

Well, at least there's an explanation and it's for a good cause.
I'll still hate working with them...

Regards.

#4

I missed Art's original e-mail - and it doesn't show up in the cdi
archive - so I presume it went to informix-list (AT) iiug (DOT) org and the
forward mechanism failed again.

Anyway, I have to agree with Art's comments. It really is a shame that
the manuals are of less quality than they were before even if it is
because, as Jonathan says, that they are designed to be easier for
visually impaired people to use.

I wouldn't mind if they were accurate! But the technical content still
seems to lag behind reality, especially in more esoteric areas. And I
notice that the text is basically the same in the Backup and Restore
Guide. I have just been trying to configure onbar with ISM and with
the new electronic manuals they can't even provide cross links between
these manuals. For those of you who haven't had that privilege,
setting up onbar refers to setting up ISM and points to the IBM
Informix: Storage Managers Administration Guide. Great. But there is
no link to that manual. So I look in the Master Index for "IBM
Informix: Storage Managers Administration Guide" and it doesn't exist
in the master index.

In the end I went back to my (t)rusty 9.3 and 9.4 manuals.

I think the concept of having a searchable master index is brilliant
(DEC had one for VAX/VMS - now how many years ago was that? ) but in
reality it isn't a small job to accomplish this and if not done
properly is more of a hindrance than a help - and that will mean more
RTFM questions on this list.

I can't wait

regards

Malcolm
Jonathan Leffler wrote:

Quote:

Fernando Nunes wrote:
Art S. Kagel wrote:

Since this is shaping up to be a slow posting day, I want to take the
opportunity to vent.

For years Informix had award winning documentation and, while it took
me a while to get used to them when they first showed up in the OL4.01
or OL5 docs, the railroad syntax diagrams were actually easy to read
and follow. The original PDFs, whether you like PDFs or not (and I
do), were easy enough to navigate with hot links in expected places.
So, why were the docs for IDS 9.40 and IDS 10.00 changed to those
hairy pseudo railroad diagrams with the footnote pointers to get to
hot links? The PDF files are now VERY difficult to navigate and the
changes did not make the HTML versions any better.

I want my old docs back! Just my opinion.

Anyone else got one on this topic? It's got to be better than "Is DB2
dead?" or whatever that thread has morphed into.

Art S. Kagel

I totally agree with you.
I'd love to move my customer to 10.00 but I fear the day when I must
browse those books... Besides being a PITA to use they're even much
uglier

If it's any consolation, I think the Tech Pubs (ID - Information
Development) people would agree - and the absence of the index letters
at the top of the index pages is a nuisance too.

However, the reason for the change is so that the manuals can be handled
by automatic systems for the visually impaired - accessibility is the
jargon usually used. The railroad diagrams can, apparently, be handled
better than the much finer ones that used to be in the Informix manuals.

IBM does a lot of work with the US federal government, and such things
are important to contracts with it.

--
Jonathan Leffler #include <disclaimer.h
Email: jleffler (AT) earthlink (DOT) net, jleffler (AT) us (DOT) ibm.com
Guardian of DBD::Informix v2005.01 -- http://dbi.perl.org/

#5

mweallans (AT) panacea (DOT) co.uk wrote:

Quote:

I missed Art's original e-mail - and it doesn't show up in the cdi
archive - so I presume it went to informix-list (AT) iiug (DOT) org and the
forward mechanism failed again.
SNIP

No Malcolm, I posted directly to the NG. But as I note the 9th was a slow
posting day, perhaps that was because things were not working properly and
the original post didn't go out to everyone and didn't make it into the
archive. I saw fewer than a dozen posts that day.

Art S. Kagel

#6

I think this could be called:

Feedback to IBM

What IBM is supposed to do is to accept that feedback, analize and with time enhance the documentation in a way that all of their customers are happy with.

The issue here, I think, is that this feedbak have to be directed properly to IBM, not y few users but many, and AFAIK a few people RTFM.

J.

-----Original Message-----
From: Fernando Nunes <spam (AT) domus (DOT) online.pt>
To: informix-list (AT) iiug (DOT) org
Date: Fri, 12 Aug 2005 10:07:31 +0100
Subject: Re: Venting about docs

Jonathan Leffler wrote:

Quote:

Fernando Nunes wrote:

Art S. Kagel wrote:

Since this is shaping up to be a slow posting day, I want to take the
opportunity to vent.

For years Informix had award winning documentation and, while it took
me a while to get used to them when they first showed up in the
OL4.01 or OL5 docs, the railroad syntax diagrams were actually easy
to read and follow. The original PDFs, whether you like PDFs or not
(and I do), were easy enough to navigate with hot links in expected
places. So, why were the docs for IDS 9.40 and IDS 10.00 changed to
those hairy pseudo railroad diagrams with the footnote pointers to
get to hot links? The PDF files are now VERY difficult to navigate
and the changes did not make the HTML versions any better.

I want my old docs back! Just my opinion.

Anyone else got one on this topic? It's got to be better than "Is
DB2 dead?" or whatever that thread has morphed into.

Art S. Kagel

I totally agree with you.
I'd love to move my customer to 10.00 but I fear the day when I must
browse those books... Besides being a PITA to use they're even much
uglier

If it's any consolation, I think the Tech Pubs (ID - Information
Development) people would agree - and the absence of the index letters
at the top of the index pages is a nuisance too.

However, the reason for the change is so that the manuals can be handled
by automatic systems for the visually impaired - accessibility is the
jargon usually used. The railroad diagrams can, apparently, be handled
better than the much finer ones that used to be in the Informix manuals.

IBM does a lot of work with the US federal government, and such things
are important to contracts with it.

Well, at least there's an explanation and it's for a good cause.
I'll still hate working with them...

Regards.

Jean Sagi
jeansagi (AT) myrealbox (DOT) com
jeansagi (AT) gmail (DOT) com

sending to informix-list

#7

Quote:

-----Original Message-----
From: owner-informix-list (AT) iiug (DOT) org
[mailto

wner-informix-list (AT) iiug (DOT) org] On Behalf Of
mweallans (AT) panacea (DOT) co.uk
Sent: Friday, August 12, 2005 2:28 AM
To: informix-list (AT) iiug (DOT) org
Subject: Re: Venting about docs

...
Informix: Storage Managers Administration Guide. Great. But there is
no link to that manual. So I look in the Master Index for "IBM
Informix: Storage Managers Administration Guide" and it doesn't exist
in the master index.

In the end I went back to my (t)rusty 9.3 and 9.4 manuals.

I think the concept of having a searchable master index is brilliant
(DEC had one for VAX/VMS - now how many years ago was that? ) but in
reality it isn't a small job to accomplish this and if not done
properly is more of a hindrance than a help - and that will mean more
RTFM questions on this list.

I can't wait

In the meantime, maybe this will help alleviate the pain... ???

http://publib.boulder.ibm.com/infoce...help/index.jsp

HTH,
Paul Mosser

sending to informix-list

#8

Thank you to Art Kagel, Malcolm Weallans and Paul Mosser who took the time
to raise suggestions for enhancing the current Informix product
documentation.

Cross-linking references to other manuals within Informix documentation is
a suggestion that has often come up. In fact, Informix had implemented it
briefly prior to the acquisition of Informix by IBM. The process of
cross-linking manuals, however, proved problematic as directory names
shifted and multiple versions of books were released. We will revisit this
issue and determine whether cross-linking references to other manuals is
possible within the IBM documentation system.

Making the documentation filenames on the doc CD and downloadable .zip file
of the complete doc set will be easier for us to address. Look for this to
be corrected in future releases.

The IBM Informix documentation team is committed to improving the user
experience with its products, and feedback such as yours helps make that
possible.

Scott
----------------------------------------
Scott Stark
sstark (AT) us (DOT) ibm.com

Quote:

-----Original Message-----
From: owner-informix-list (AT) iiug (DOT) org
[mailto

wner-informix-list (AT) iiug (DOT) org] On Behalf Of
mweallans (AT) panacea (DOT) co.uk
Sent: Friday, August 12, 2005 2:28 AM
To: informix-list (AT) iiug (DOT) org
Subject: Re: Venting about docs

...
Informix: Storage Managers Administration Guide. Great. But there is
no link to that manual. So I look in the Master Index for "IBM
Informix: Storage Managers Administration Guide" and it doesn't exist
in the master index.

In the end I went back to my (t)rusty 9.3 and 9.4 manuals.

I think the concept of having a searchable master index is brilliant
(DEC had one for VAX/VMS - now how many years ago was that? ) but in
reality it isn't a small job to accomplish this and if not done
properly is more of a hindrance than a help - and that will mean more
RTFM questions on this list.

I can't wait

In the meantime, maybe this will help alleviate the pain... ???

http://publib.boulder.ibm.com/infoce...help/index.jsp

HTH,
Paul Mosser
sending to informix-list

Thread Tools
Show Printable Version Email this Page
Display Modes
Linear Mode Switch to Hybrid Mode Switch to Threaded Mode

Re: Venting about docs

comp.databases.informix comp.databases.informix

Re: Venting about docs - 08-11-2005 , 04:04 PM

Re: Venting about docs - 08-12-2005 , 12:31 AM

Re: Venting about docs - 08-12-2005 , 04:07 AM

Re: Venting about docs - 08-12-2005 , 04:28 AM

Re: Venting about docs - 08-12-2005 , 08:23 AM

Re: Re: Venting about docs - 08-12-2005 , 09:52 AM

RE: Venting about docs - 08-12-2005 , 04:13 PM

Re: Venting about docs - 08-22-2005 , 03:03 PM