Possible improvement to Calc Guide

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

Stephen Fanning schreef op 13.03.2020 18:14:

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!).

It is indeed a large document and not easy to read. But if you want to find a specific function you can use the search funtion to find information about that function.

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.

True, but you have to know the name of the funtion to use it, or scroll down the functions to find what you need.

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
Documentation/Calc Functions - The Document Foundation Wiki).

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.

That certainly needs improvement.

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.

I looked at your document and see that it contains less pages. It wend from 90 to 70 pages. Still a large document but the informations is more clear I think. And it is indeed good to make it consstent to the Wizzard and the Help pages.

Regards, Kees

My suggestion is to break Appendix B out into a book of its own, with
each function having its own chapter. Each chapter provides:
* Where and when the function would usually be used;
* When the function should not be used;
* The limitations of the various variables within the function;
* Where the function fails, and what to do, when it does fail;

I've started writing such a critter several times, but get side tracked
by other things that are semi-documented/undocumented/incorrectly
documented. This is an addition to finding work-arounds for things that
LibO can't do. (Shinji Enoki merely scratched the surface, in his talk
at Almeria last year.)

Jacques Tiberghien
_The Pascal Handbook_.
Sybex INC: 1981
ISBN: 0-89588-053-9
is the guide example I'm following.

But
B Held & T Richardson
_Microsoft Excel Functions and Formulas, Third edition_
Dulles VA: Mercury Learning and Information: 2015
ISBN: 978-1-937585-50-1
as does a book called something like _100 Formulas for Excel_.
(I can't find it on my drive. I'm running a script within Calibre, so it
isn't accessible, to find the correct title, or publication data.)
are pointers towards what I'm envisioning.

In an ideal world, we'd have
* LibreOffice For the Biological Sciences;
* LibreOffice For Business Statistics;
* LibreOffice For Educational and Psychological Statistics;
* LibreOffice For Engineering Statistics;
* LibreOffice For Environmental Sciences and Statistics;
* LibreOffice For Health Services management Statistics;
* LibreOffice For Human Resource Statistics;
* LibreOffice For Marketing Statistics;
* LibreOffice For Social Science Statistics;
* LibreOffice For Data Analysis;
* LibreOffice For Project Management;
* LibreOffice For Financial Analysis;
* LibreOffice For Economic Appraisal and Forecasting;
* LibreOffice For Stock Market Analysis;
* LibreOffice For Financial Simulation Modelling;

FWIW, I simply substituted "Excel" or "Excel 2016" with LibreOffice, to
create those titles.

jonathon

I think that a 500 chapter book would be daunting.  I would suggest it be Chapters that cover a group of similar functions. Ones that only vary slightly or have a common purpose.  An example would be all the amortization, future values, payment amount, and so on.

I do think that the functions need more explanation and examples of how to be used.   I also think that these functions will not change significantly over the years so a stand alone volume of Calc Functions would be a good way to go.

John Hart