Hello Steve and all team
(snip)
In working through this chapter I have found a range of problems with the
Function Wizard and the (built-in / online) Help pages. These fall into
three rough categories:
(1) Cases where the Help system doesn't address a function (see earlier
email). An obvious knock-on in these cases is that the Help button on the
Function Wizard won't work sensibly for these functions.
Yes. Chapter 18 has a very dense contents.
(2) Cases where although the Help system does include a function's
description, the Help button on the Function Wizard doesn't appear to be
linked to the correct item in the Help system.
I am aware of the issue of some dialogs Help button not opening the
right Help page for the function or tab displayed. It is a bug. But if
you click on any function argument text box and press F1, you will
likely to get the right page, though.
(3) Cases where there are inconsistencies between the description of a
function in the Help system and its implementation in the Function Wizard.
This is hard and very time consuming to fix. A systematic review will
consume an enormous amount of time, besides requiring deep knowledge on
the function purpose. We try to fix these inconsistencies ad-hoc, when a
bug report pops.
Another issue that may rise is: Which side is wrong? the Help page or
the function implementation in the wizard? There is no clear answer
because the Help page can serve as reference for the software, but the
software can also evolve and turn the help page inconsistent or
obsolete. There are a number of cases where the functions arguments have
changed in the past and the help page was not updated.
(In some cases I had to pick the QA test files in the source code to
verify the consistency of the Help content).
I suspect the most efficient way for me to proceed is to carry on updating
the chapter and at the end of my task, raise all the problems / bugs /
inconsistencies in one go. At that point I'll try to avoid covering
problems that are already in the system (e.g. the inclusion of OPT_
functions in the Help).
Does that make sense?
Perfect sense. What is most needed in documentation and Help here are
many pairs of eyes, that can report inconsistencies (please use
bugzilla). If you don't mind, please open bug reports on individual issues.
Kind regards
Olivier