Documentation gripe

[jimdempseyatthecove]

I am using Intel Visual Fortran from Parallel Studio XE installed in Visual Studio.

The problem I have is your integration of the Visual Fortran documentation into Visual Studio which has MS C++, Intel C++ and other languages.

Using the VS help index is not almost useless. Example, I am in VS in a Fortran solution and project and click

Help | Intel Visual Fortran Composer XE 2011 | Fortran Composer XE 2011 Help

Then click on Index tab, then enter OPERATOR hoping to find information on IFV operator functions.
This brings up ~800 references to OPERATOR almost all of which are not IVF.

I know this is easy to blame MS VS for this problem, but Intel chose to integrate IVF documentation into VS.

Note, older version of MS VS had a filter option, whereby the index could be filtered by installed application (MS C++, Visual Basic, ... Intel...) but this is now not available.

I plead to you to address this issue. The most logical choice would be to ask MS to restore the filter to index .AND. search. Lacking their cooperation, seperate your documentation from VS.

Jim Dempsey

[TimP]

The Intel compiler documentation is accessible separately from VS on the start menu
Intel Parallel Studio > documentation (link to .chm file)

[JohnNichols]

I appreciate the documentation is available in both flavours, but I still mainly use the Fortan PowerStation Reference Manuals and the older Microsoft Fortran Manuals. The examples are often directly shown in IVF manuals as from the MSF manuals.

A PDF file would really really help so I can study it at night like a real book.

I hate your current methods.

JMN

[IanH]

The VS2010 help system (as opposed to previous VS versions) was a retrograde move in so many ways.

Another alternative...



I wrote off half a day recently because I was inadvertently blundering around in the help for 12.0 rather than 12.1.

[dboggs]

I agree about the problems of "modern documentation" compared to the older style in a book. The modern style is good for browsing while working in Fortran in front of the computer, but it's terrible for off-line browsing and actually LEARNING about the system.

We tried actually PRINTING the help document, but it's simply not formatted well for this purpose. For every 100 pages of "paper real estate", for example, about 20 or 30 of them are simply devoted to a list ofcoming-up-next topics. The page turning is terrible compared to what we would have received at one time in a proper book.

I have an ancient bona-fide book called "Digital Visual Fortran Programmer's Guide" by Etzer & Dickenson, and "Compaq Fortran Language Reference Manual" by Compaq Computer Corp, which are reserved for bedside and in-front-of-TV use. These are much better for learning. Too bad they can't be updated and made available in IVF versions.

[Steven_L_Intel1]

Personally, I agree that PDF and printed documentation is better. But it's difficult and costly to do both that and the online-indexed form usable from Visual Studio. We did actually print an Intel version of the Language Reference Manual - I have a copy. But so few people bought it that it was discontinued. It doesn't help that Microsoft keeps changing their design for the "help viewer" forcing rework.

[jimdempseyatthecove]

Ok then, why doesn't

(in Visual Studio) Help | Intel Visual Fortran XE 2011 | Intel Visual Fortran XE 2011 Help

take you to the same place?

From the splash screen of the " start menu | Intel Parallel Studio... > documentation"

You read:

"The documentation is integrated in Microsoft Visual Studio* integrated development environment (IDE) Document Explorer.

Launching Help in Microsoft Visual Studio

From the Help menu, choose Intel Visual Fortran Composer XE 2011 > Intel Visual Fortran Composer XE 2011 Help."

With VS 2010 we lost the "filtered by" capability. Although you can still browse the contents within Intel Fortran, it is not functionally equivalent of using the Index (within VS help to show indexed items within the selected installed component).

Just a minor gripe...

Jim

[jimdempseyatthecove]

>> "I agree that PDF and printed documentation is better...It doesn't help that Microsoft keeps changing their design for the "help viewer" Quote from Steve Lionel

Can there be any more convincing argument for favoring PDF-only over VS help integration than a quote from Dr. FORTRAN?

Your VS help integration would then be simplified to providing a hyperlink to the (installed)PDF.

Oh, one more thing.

When (if) you elect to do PDF documentation, hire a good programmer/technical writer to produce a good (read usable): Index, table of contents, and more importantantly produce cohesive/comprehensive information on the selected item. IMHO there is nothing worse than having to have the (PDF) help documentation open in four windows to try to piece together what could have been said in one place.

As a training exercize for your technical writers, give them some 1980's vintage Borland Turbo C or similarly writtenFortran documentation and say: Produce documentationin equivilent representation. Things were done much better prior to auto-generation of documentaiton.

Jim

[Steven_L_Intel1]

If you feel strongly about it, please make your request known through Intel Premier Support. My opinion on this matter is known. But it isn't simple - the tools our writers use to develop the documentation in a format suitable for the MS Help Viewer don't make it easy to create PDFs. If it was just throwing a switch, it would be done.

[JohnNichols]

Steve:

Your premier support is a real pain to use and log onto.

JMN

[IanH]

Quoting jimdempseyatthecove

>> "I agree that PDF and printed documentation is better...It doesn't help that Microsoft keeps changing their design for the "help viewer" Quote from Steve Lionel

Can there be any more convincing argument for favoring PDF-only over VS help integration than a quote from Dr. FORTRAN?

Your VS help integration would then be simplified to providing a hyperlink to the (installed)PDF.

Nooooooo........

The VS 2010 help viewer certainly has issues, but holus-bolus conversion of all help to PDF would be far, far worse. Even Adobe Reader has moved away from that!

[jimdempseyatthecove]

>> If it was just throwing a switch, it would be done.

And that is what is systemic with the current generation of technical writers...
They don't write - the rely too much on throwing switches.

RE: make your request known through Intel Premier Support

Posts in the public forumprovides exposure to gripes, exposure (when appropriate) breeds clamor, clamor breeds awareness, awareness breedsaction, action yields results. This is all constructive criticism. Hopefully, resulting in better documentation. Read better for the user, and not better (reducing effort) for the technical writer.

Jim Dempsey

[Steven_L_Intel1]

The writers are very busy writing - but they also have to spend too much of their time redoing existing work because of changes in the underlying tools. Our writers are wonderful - and they've been with us since the DEC days - but their work has a lot of overhead.