Re: [libreoffice-documentation] Suggestion
Hi Ilmari, Ilmari Lauhakangas schrieb am 27-Nov-19 um 16:59: Regina Henschel kirjoitti 27.11.2019 klo 12.51: Hi, Ilmari Lauhakangas schrieb am 27-Nov-19 um 10:29: 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 -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
Re: [libreoffice-documentation] Help pages for CALC functions OPT_* (Bug 92084)
Hello Steve Yes it is interesting. The bug on Doc is already opened since ages: https://bugs.documentfoundation.org/show_bug.cgi?id=92084 If you want to write a piece of Help page, please follow the outline of the other Help Calc functions description/syntax/example/related/ in a simple Writer document and I'll convert to the Help XML. I will commit the patch with your authorship. Regards Em 27/11/2019 12:56, Steve Fanning escreveu: > Hi Olivier, > > A couple of weeks ago you mentioned Bug 92084, which relates to the > absence of information in the Help files for the OPT_BARRIER, > OPT_PROB_HIT, OPT_PROB_INMONEY, and OPT_TOUCH functions. > > Appendix B of the 4.1 Calc Guide contains descriptions for each of these > four functions. Could that material be used to populate the missing Help > pages? > > Regards, > > Steve > -- Olivier Hallot LibreOffice Documentation Coordinator Comunidade LibreOffice Rio de Janeiro - Brasil - Local Time: UTC-03:00 http://tdf.io/joinus -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
[libreoffice-documentation] Help pages for CALC functions OPT_* (Bug 92084)
Hi Olivier, A couple of weeks ago you mentioned Bug 92084, which relates to the absence of information in the Help files for the OPT_BARRIER, OPT_PROB_HIT, OPT_PROB_INMONEY, and OPT_TOUCH functions. Appendix B of the 4.1 Calc Guide contains descriptions for each of these four functions. Could that material be used to populate the missing Help pages? Regards, Steve -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
[libreoffice-documentation] Help pages for CALC functions OPT_* (Bug 92084)
Hi Olivier, A couple of weeks ago you mentioned Bug 92084, which relates to the absence of information in the Help files for the OPT_BARRIER, OPT_PROB_HIT, OPT_PROB_INMONEY, and OPT_TOUCH functions. Appendix B of the 4.1 Calc Guide contains descriptions for each of these four functions. Could that material be used to populate the missing Help pages? Regards, Steve -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
Re: [libreoffice-documentation] New Member
Dimona Delvere kirjoitti 27.11.2019 klo 18.07: My name is Dimona. I am looking forward to join Libre Office community. I have some experience in technical writing, video tutorial creation, marketing and journalism. I am fluent in English and Russian. My current aim is to develop further my documentation writing skills. I am wondering if I could contribute to your books? I believe that I need to access the Documentation cloud, and receive a user ID? Yes, like Olivier said, create a username for our web services: https://wiki.documentfoundation.org/Infra/SingleSignOn Then directly email Olivier. Adding you to CC as well in case you are not getting emails. Olivier's reply is https://listarchives.libreoffice.org/global/documentation/msg13383.html Ilmari -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
[libreoffice-documentation] New Member
Hello Everyone, My name is Dimona. I am looking forward to join Libre Office community. I have some experience in technical writing, video tutorial creation, marketing and journalism. I am fluent in English and Russian. My current aim is to develop further my documentation writing skills. I am wondering if I could contribute to your books? I believe that I need to access the Documentation cloud, and receive a user ID? Many Thanks, Dimona Dimona Delvere -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
Re: [libreoffice-documentation] Suggestion
Regina Henschel kirjoitti 27.11.2019 klo 12.51: Hi, Ilmari Lauhakangas schrieb am 27-Nov-19 um 10:29: 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 -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
Re: [libreoffice-documentation] Suggestion
Hi, Ilmari Lauhakangas schrieb am 27-Nov-19 um 10:29: 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 -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
Re: [libreoffice-documentation] Suggestion
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. 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 On Wed, 27 Nov 2019 at 01:09, Jean Weber wrote: On Tue, 26 Nov 2019 at 18:13 Olivier Hallot < olivier.hal...@libreoffice.org> wrote: Hi Steve Em 26/11/2019 11:00, Stephen Fanning escreveu: 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 -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
Re: [libreoffice-documentation] Suggestion
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 On Wed, 27 Nov 2019 at 01:09, Jean Weber wrote: > On Tue, 26 Nov 2019 at 18:13 Olivier Hallot < > olivier.hal...@libreoffice.org> > wrote: > > > Hi Steve > > > > Em 26/11/2019 11:00, Stephen Fanning escreveu: > > > 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 > > > > > > -- > To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org > Problems? > https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ > Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette > List archive: https://listarchives.libreoffice.org/global/documentation/ > Privacy Policy: https://www.documentfoundation.org/privacy > -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy