Complete online documentation and help files

Share icon

Another poster mentioned a planned overhaul of Igor Pro/Wavemetrics online presence. In that regard, I think complete online documentation and help files would be a great addition to Igor Pro. It would be ideal if searching them could be integrated with searching Igor Exchange, where some queries have been addressed more directly.

Search engines landing on Igor docs would also be something of an advertisement for Igor. The help files are remarkably transparent and the built-in functions are flexible in ways that they're sometimes not in comparable analysis programs.
I have come across https://www.wavemetrics.com/products/igorpro/manual.htm in the past, but I find it sub-optimal in many ways.

First, downloading (and opening) a PDF should be unnecessary. Second, ctrl+F in a PDF is not as flexible as a search engine (or a dedicated search on Igor's site). Third, I think it would be better organized and easier to navigate if each operation and function had its own web page.

Those PDFs aren't easily searchable from a search engine. For example, I just picked a random procedure, StatsANOVA2Test, and searched it in google. Only one Wavemetrics webpage comes up (mentioning it in a bug fix; though posting this will change the search results), and that page does not lead to any StatsANOVA2Test section of the manual.

I've always been a bit perplexed by the disconnect between Igor's online presence and day-to-day use of the program. Taking the StatsANOVA2Test search a little further as an example, searching "stats anova test igor" on google leads to the Statistical Tests section Igor's overview on www.wavemetrics.com and one finds examples using StatsANOVA2Test. Wouldn't it be nice if there was a link to the full description of that procedure?

December 20, 2017 at 06:27 am - Permalink

aoa wrote:
I have come across https://www.wavemetrics.com/products/igorpro/manual.htm in the past, but I find it sub-optimal in many ways.

First, downloading (and opening) a PDF should be unnecessary. Second, ctrl+F in a PDF is not as flexible as a search engine (or a dedicated search on Igor's site). Third, I think it would be better organized and easier to navigate if each operation and function had its own web page.

Those PDFs aren't easily searchable from a search engine. For example, I just picked a random procedure, StatsANOVA2Test, and searched it in google. Only one Wavemetrics webpage comes up (mentioning it in a bug fix; though posting this will change the search results), and that page does not lead to any StatsANOVA2Test section of the manual.

I've always been a bit perplexed by the disconnect between Igor's online presence and day-to-day use of the program. Taking the StatsANOVA2Test search a little further as an example, searching "stats anova test igor" on google leads to the Statistical Tests section Igor's overview on www.wavemetrics.com and one finds examples using StatsANOVA2Test. Wouldn't it be nice if there was a link to the full description of that procedure?


For some reason, if I Google for "StatsANOVA2Test" I don't get the hit that's in the .pdf manual unless I click the link at the bottom of the results page that says "If you like, you can repeat the search with the omitted results included.". The search widget on https://www.wavemetrics.com/products/igorpro/manual.htm is clearly broken. That used to work right, but at some point Google changed how these widgets work and we didn't keep up with the times.

I agree with you 100% that it would be great if our documentation was all online, searchable, etc. The biggest problem is that we don't currently have the documentation in a format that is conducive to converting to HTML, and so doing the conversion would be a *lot* of work. About 10 years ago Howard and I worked on trying to convert our FrameMaker documentation (which is used to produce the .pdf files) into HTML. The HTML output didn't look very good and needed a lot of manual cleanup. This is partially due to how we've formatted the documentation in FrameMaker itself, but cleaning up the documentation in FrameMaker before exporting would also be very labor intensive.

This is still on our radar, but we're a small company and this is a big task.

December 20, 2017 at 07:15 am - Permalink

aclight wrote:
For some reason, if I Google for "StatsANOVA2Test" I don't get the hit that's in the .pdf manual unless I click the link at the bottom of the results page that says "If you like, you can repeat the search with the omitted results included.". The search widget on https://www.wavemetrics.com/products/igorpro/manual.htm is clearly broken. That used to work right, but at some point Google changed how these widgets work and we didn't keep up with the times.
I see what you mean--it does come up once you choose to show omitted results.

aclight wrote:
This is still on our radar, but we're a small company and this is a big task.
That does sound like an unfortunate situation! I hope that you find a way to convert them efficiently in the long run.

December 20, 2017 at 08:45 am - Permalink

aclight wrote:
The biggest problem is that we don't currently have the documentation in a format that is conducive to converting to HTML, and so doing the conversion would be a *lot* of work. About 10 years ago Howard and I worked on trying to convert our FrameMaker documentation (which is used to produce the .pdf files) into HTML. The HTML output didn't look very good and needed a lot of manual cleanup.


According to Wikipedia the latest framemaker version has "customizable basic HTML5 output", I have no clue how good that is though. Maybe it is worth a quick trial.

I totally agree that doing something like that *manually* is a lost cause.

December 22, 2017 at 04:23 am - Permalink

thomas_braun wrote:
aclight wrote:
The biggest problem is that we don't currently have the documentation in a format that is conducive to converting to HTML, and so doing the conversion would be a *lot* of work. About 10 years ago Howard and I worked on trying to convert our FrameMaker documentation (which is used to produce the .pdf files) into HTML. The HTML output didn't look very good and needed a lot of manual cleanup.


According to Wikipedia the latest framemaker version has "customizable basic HTML5 output", I have no clue how good that is though. Maybe it is worth a quick trial.

I totally agree that doing something like that *manually* is a lost cause.

The biggest problem (as I understand it) is that we often use tabs and/or formatting options (setting margins and tab stops for a text format) to create what appear to be tables, instead of actually using a FrameMaker table. Because whitespace is collapsed in HTML, we end up with a pretty poor representation of the original "table" when converted to HTML. Take the "Chart" operation as an example--the parameters list is likely not formatted in FrameMaker as a table.

We're also not using the latest FrameMaker version, though I don't remember which version it is that we're using.

December 22, 2017 at 05:01 am - Permalink

Quote:
According to Wikipedia the latest framemaker version has "customizable basic HTML5 output", I have no clue how good that is though. Maybe it is worth a quick trial.


Actually they claim to have "Next-generation Responsive HTML5 layouts". But the latest FrameMaker can not save our gargantuan manual to PDF at all - it hangs. I am attempting to work with Adobe on this.

Quote:
The biggest problem (as I understand it) is that we often use tabs and/or formatting options (setting margins and tab stops for a text format) to create what appear to be tables


That is no longer the case. I turned all tables into real tables.

However, we use tables in tables quite a bit in the reference chapter and FrameMaker's does not support that except through a kludge (text frame containing sub-table in table cell) that would probably not be correctly translated to HTML.

December 22, 2017 at 06:57 am - Permalink