I would like to hear the opinions of members of the Documentation Team on a
potential improvement to the Calc Guide.
As you probably know, Calc provides a library of over 500 functions. The
6.2 Calc Guide includes an Appendix B entitled Description of Functions
which occupies over 70 pages (not an enjoyable read!).
Calc's Function Wizard provides the user with facilities that help insert a
function call into a cell, providing text explanations that indicate the
purpose of the function and giving high level details about the function's
parameters. In addition, the Help pages provide further relevant details of
each function, including examples.
Behind the scenes we are also developing a wiki area to provide yet more
detail on the Calc functions, aimed at covering any technical details that
are beyond the scope of the Help pages (see
https://wiki.documentfoundation.org/Documentation/Calc_Functions).
Having been responsible for the major update to Appendix B in the 6.2 Calc
Guide, I am unsure of the role of the information in that appendix. At the
moment it is not entirely consistent with the text in the Function Wizard,
nor is entirely consistent with the text in the Help pages. There is
therefore scope for conflict and / or confusion between these various
sources.
I would like to propose that the appendix in the Calc Guide be updated so
that it provides exactly the same information as is on the Function Wizard
- no more information, no less information and no "improved" text. This
would have two main advantages:
(1) The English text on the Function Wizard is readily available as preset
strings in the code, embedded in various .hrc files. This means that the
new appendix would be easily created (I've done it and placed a draft copy
in Nextcloud; see file CG6418-CalcFunctions-SF-13Mar2020.odt in the
English/Calc Guide/Related materials/ folder) and, importantly, can be
easily checked by a reviewer who has no specialist knowledge.
(2) Browsing functions in the Function Wizard requires many mouse clicks -
having a set of straightforward tables containing the same information in
the Calc Guide may be useful to some users, helping them to discover
functions that they were not previously aware of.
I would be interested in your thoughts.
Regards,
Steve Fanning