Suggestion

Olivier,

As you are aware I have noted some discrepancies between the Function
Wizard and the Help system with regards to the descriptions of the 500+
Calc functions. I have kept a list of the issues found so far and will
raise bugs in due course.

However the scope of cross-checking the available sources of information is
wide and I’ve only really scratched the surface so far while updating the
relevant Calc Guide chapter.

Once I have completed the draft Calc Guide chapter, I would be prepared to
carry out a more systematic and thorough cross-check of the function
descriptions over the next few months, as a background task. Would that a
worthwhile exercise?

Regards,

Steve

Hi Steve

Olivier,

As you are aware I have noted some discrepancies between the Function
Wizard and the Help system with regards to the descriptions of the 500+
Calc functions. I have kept a list of the issues found so far and will
raise bugs in due course.

I am interested in these discrepancies because the Help system is
actually the reference information to users. Therefore, information
accuracy in the Help system is a quality issue and must be addressed.

However the scope of cross-checking the available sources of information is
wide and I’ve only really scratched the surface so far while updating the
relevant Calc Guide chapter.

Right, not a perfect world. LibreOffice implements both OpenDocument
Formula Function standard (ODFF) as well as many Excel function for
interoperability. Some function names are the same but with different
results or arguments, depending on several external factors (Excel
version, Excel change in naming and so on).

Once I have completed the draft Calc Guide chapter, I would be prepared to
carry out a more systematic and thorough cross-check of the function
descriptions over the next few months, as a background task. Would that a
worthwhile exercise?

In the Calc Guide point of view, my personal opinion is that it can turn
the chapter into an extensive reference, which can turn the book a bit
too heavy, having pages and pages of esoteric
math/sciences/financial//computer sciences/.../ functions, perhaps
better fit into a "Handbook of LibreOffice Calc Functions" book on its own.

Would that be a worthwhile exercise? yes definitely. Everyone will benefit.

Help system: must be as accurate as possible with respect to the current
software implementation.

the "Handbook": will be a wonderful piece of work for LibreOffice Calc.
500 or more functions is not a small task, though.

Note: We often see a mix of objective in product documentation blurring
  Reference info and Guide info. To try to make things a bit clear, the
software Help system must be reference-oriented, where information is
factual and accurate (and dull). For example, the Help system should not
be used to explain the math behind the COS function. The same COS
function can figure in a Guide with some trigonometry background info to
help user in achieving a goal, because Guides are essentially
goal-oriented information.

Cheers

PS ODFF 1.2 standard is described in
http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part2.html

Hi Steve

> Olivier,
>
> As you are aware I have noted some discrepancies between the Function
> Wizard and the Help system with regards to the descriptions of the 500+
> Calc functions. I have kept a list of the issues found so far and will
> raise bugs in due course.

I am interested in these discrepancies because the Help system is
actually the reference information to users. Therefore, information
accuracy in the Help system is a quality issue and must be addressed.

>
> [...]
>
> Once I have completed the draft Calc Guide chapter, I would be prepared
to
> carry out a more systematic and thorough cross-check of the function
> descriptions over the next few months, as a background task. Would that a
> worthwhile exercise?

In the Calc Guide point of view, my personal opinion is that it can turn
the chapter into an extensive reference, which can turn the book a bit
too heavy, having pages and pages of esoteric
math/sciences/financial//computer sciences/.../ functions, perhaps
better fit into a "Handbook of LibreOffice Calc Functions" book on its own.

Would that be a worthwhile exercise? yes definitely. Everyone will benefit.

Help system: must be as accurate as possible with respect to the current
software implementation.

the "Handbook": will be a wonderful piece of work for LibreOffice Calc.
500 or more functions is not a small task, though.

Note: We often see a mix of objective in product documentation blurring
  Reference info and Guide info. To try to make things a bit clear, the
software Help system must be reference-oriented, where information is
factual and accurate (and dull). For example, the Help system should not
be used to explain the math behind the COS function. The same COS
function can figure in a Guide with some trigonometry background info to
help user in achieving a goal, because Guides are essentially
goal-oriented information.

IMO the functions chapter should be a separate handbook, not part of the

Calc Guide itself. Years ago when the first iteration of the book was being
written, I argued against including it, but others wanted it in. To me the
Calc Guide (and all the guides) should be task- or goal-oriented (how to do
things), not reference books.

Jean

I agree that it would be good to create a separate handbook to describe
Calc's functions and I will spend time creating a first draft of this
during the coming months.

As for the relevant chapter in the Calc Guide, I worry that it is now too
thick following the addition of so many new functions. My latest draft is
80+ pages. I suggest we retain it for the moment but I'll try too remove
excess verbage from descriptions that appear unnecessarily detailed. It
would be nice to shorten it a bit before issue!

I tend to agree with Jean and so when a separate handbook becomes
available, the chapter should be withdrawn from future issues of the Calc
Guide.

Regards,

Steve

Maybe the Help content for functions could be used as a reference template with some automation to combine it with math background etc. to finally produce a separate handbook? Just thinking of how to avoid repetition of work and human errors.

Ilmari

Stephen Fanning kirjoitti 27.11.2019 klo 11.17:

Hi,

Maybe the Help content for functions could be used as a reference template with some automation to combine it with math background etc. to finally produce a separate handbook? Just thinking of how to avoid repetition of work and human errors.

Ilmari

Stephen Fanning kirjoitti 27.11.2019 klo 11.17:

I agree that it would be good to create a separate handbook to describe
Calc's functions and I will spend time creating a first draft of this
during the coming months.

The mathematical definition of most of the functions is in the standard. It would be far too error-prone and far too time-consuming to write these definitions ourself. The help pages could get links to the HTML version of the standard or a reference with part and section number.

We need a mathematical description of those functions, which are our own function, e.g. EASTERSUNDAY. Those functions should get each an own help page with the mathematical definition or a page in the WIKI.

Some of our own functions are designed for to be compatible with Excel and have differences to similar functions in the standard. For those functions it is important to describe these differences.

In general, the fact, whether a function follows the standard or is compatible to Excel or is totally our own function, should be noted.

Kind regards
Regina

Regina Henschel kirjoitti 27.11.2019 klo 12.51:

Hi,

Maybe the Help content for functions could be used as a reference template with some automation to combine it with math background etc. to finally produce a separate handbook? Just thinking of how to avoid repetition of work and human errors.

Ilmari

Stephen Fanning kirjoitti 27.11.2019 klo 11.17:

I agree that it would be good to create a separate handbook to describe
Calc's functions and I will spend time creating a first draft of this
during the coming months.

The mathematical definition of most of the functions is in the standard. It would be far too error-prone and far too time-consuming to write these definitions ourself. The help pages could get links to the HTML version of the standard or a reference with part and section number.

We need a mathematical description of those functions, which are our own function, e.g. EASTERSUNDAY. Those functions should get each an own help page with the mathematical definition or a page in the WIKI.

Some of our own functions are designed for to be compatible with Excel and have differences to similar functions in the standard. For those functions it is important to describe these differences.

In general, the fact, whether a function follows the standard or is compatible to Excel or is totally our own function, should be noted.

So in your view, the function reference could be removed from Calc guide book and forget the idea to create a separate handbook? It would certainly make things easier for book authors.

Ilmari

Hi Ilmari,

Regina Henschel kirjoitti 27.11.2019 klo 12.51:

Hi,

Maybe the Help content for functions could be used as a reference template with some automation to combine it with math background etc. to finally produce a separate handbook? Just thinking of how to avoid repetition of work and human errors.

Ilmari

Stephen Fanning kirjoitti 27.11.2019 klo 11.17:

I agree that it would be good to create a separate handbook to describe
Calc's functions and I will spend time creating a first draft of this
during the coming months.

The mathematical definition of most of the functions is in the standard. It would be far too error-prone and far too time-consuming to write these definitions ourself. The help pages could get links to the HTML version of the standard or a reference with part and section number.

We need a mathematical description of those functions, which are our own function, e.g. EASTERSUNDAY. Those functions should get each an own help page with the mathematical definition or a page in the WIKI.

Some of our own functions are designed for to be compatible with Excel and have differences to similar functions in the standard. For those functions it is important to describe these differences.

In general, the fact, whether a function follows the standard or is compatible to Excel or is totally our own function, should be noted.

So in your view, the function reference could be removed from Calc guide book

The list (in appendix B) is not needed in a book. There exist already two lists in the UI and the list in the book has not really more information. In case you want to keep the list, it should be extended with the information, whether this function is compatible to Excel and whether it is standard or own function. That information is needed for interoperability and currently no where available.

  and forget the idea to create a separate handbook?

Yes. The huge number of functions makes it almost impossible to present and maintain the information in a book. Having the information in the Help or in the Wiki, the work can be distributed to several people. It is not necessary that all pages are finished at the same time. And you can more easily add additional material, e.g. use cases, example sheets, links.
Working on the Wiki would be more open, and allows discussions about presenting the content and about its correctness. Only a good structure and guidelines for the authors are needed. Otherwise it will become an unappealing mess.
I prefer the Wiki because even people who only want to do something occasionally can easily contribute. And authors can edit those pages, for which they have a background. Someone who works on financial functions might know nothing about functions with complex numbers, for example. Translating of such Wiki pages is easier and can be more up-to-date than translating a book. The large number of pages speaks against the help. With mathematical definition and application examples, you can quickly reach three pages per function. This results in a volume of about 1500 pages.

Kind regards
Regina

With respect to the Calc Guide, I feel that the current chapter has value as a simple list of what's available, presented in a straightforward format.

However if we feel that it should be removed, then it would be good to decide soon so that no further effort need be expended on updating it.

Regards,

Steve