Re: [libreoffice-documentation] some thoughts on the structure of the Help article
Hello Lera I think your scheme can turn into a wiki page to guide autors on how to improve the description of Calc functions in Help content. There will be a trade off between being prolific and be effective. In my opinion, the help page on Calc function must bring the user on how to use the function in his work. I'll let the teaching of the theory behind the function to a link to the entry at Wikipedia to guide user into the theory. I cant make a statement on the level of details of your regular expression explanations, as it is very subjective, but I decided to shorten it in my translation. On lexemes, be aware that Pootle and off-line translation tools have the tips you mention (translation memory) and is a matter of choice for the translator(*). These tools work paragraph by paragraph and are very effective to assist the translators. I think this is a non-issue, and the rule-of-thumb is to never builds a sentence with an assemblage of individual words. On the example table, I could not translate the words without breaking the example just below. So I changed the words to and changed the function examples. The issue is that is adds noise to the translation memory, because pen, pencil were translated to other objects unrelated. I have no solution to that (except implement a manual control to prevent memorization) regards Olivier (*) offline tools were used when Pootle was not so performant (or for bulk changes). Now I consider Pootle my first choice (minus some UI bugs). Em 03/12/2015 19:23, Lera escreveu: > Hi, > > This letter is written because of the bug report #95968 [1]. So it is > connected with my work in the documentation team, and I want to do work of > high quality and without causing inconvenience to other community members. I > would like to clarify some appeared issues in reports #95968, #95496 [2] and > discuss them. > Everything that is said in this letter can be assigned to any help topic. But > I will talk only about Calc functions, because 486 pages in the Help can > include connected mistakes, in addition, the letter will be considerably > shorter. > My professional activities and my education give me a notion of the full life > cycle of software, including documentation. However, I can also be partly > wrong. In addition, I tend to believe that in the open societies all > decisions > should be made together, and if we can not agree with standards, we need to > change them. Therefore, I would like to offer a discussion on how we should > further proceed with the Help development. I'm not a native English speaker, > so please ask questions, if I can not deliver my idea clearly enough. I would > like to get your opinion as well, if possible. > > This is my vision of the structure of Calc function articles. > > 1. Article title > Title of the article should be brief, but give enough information about what > will be discussed below. This should include specific terms, which allow the > user to know exactly that he sees the page he/she wants. > For example, if the page is called TIME, one can not be sure that he reads > the > right page until he start reading some further text on the page. Although it > seems a trifle, it may take time and cause some user irritability if he > mistakenly hits an unneeded article. Our goal as the documentation team is to > help the user find solutions to his issues, but without brain temperature > increase. This situation will arise when we use the TIME, DATE, DAY, > TRANSPOSE, STYLE, and others for an article title. > For example, in my opinion, instead of title just “TIME” we must provide > “TIME > function”. > > 2. Brief description of why this function is needed, and what it returns > This item is most needed for the people who have experience of using Calc, > but > did not use this particular function. Therefore, information about what the > function does and what results are returned should be included. > For example (IMCOS function): > In theory (but not in Calc), a complex number can be represented as a special > type of number (e.g. looks like Scientific format in Calc) or as an array of > two cells (e.g. looks like a result of some array functions in Calc). But in > Calc complex number is returned as a string “a+bi” in one cell. You can check > it with the help of the ISNONTEXT function. If we write in the Help article > only that the function returns the cosine of a complex number, but don't say > in which form, then the user, who does not use this function, may not know > that the result is returned as a string, because it is unusual for Calc. > That's why, the type of the returned value must be clearly specified, > especially if this can be misinterpreted. > > 3. Way of working for complex functions > This item is required for functions, whose work may vary depending on the > implementation. A user needs to understand how it works, because in some > situations it can provide a surprise result
[libreoffice-documentation] some thoughts on the structure of the Help article
Hi, This letter is written because of the bug report #95968 [1]. So it is connected with my work in the documentation team, and I want to do work of high quality and without causing inconvenience to other community members. I would like to clarify some appeared issues in reports #95968, #95496 [2] and discuss them. Everything that is said in this letter can be assigned to any help topic. But I will talk only about Calc functions, because 486 pages in the Help can include connected mistakes, in addition, the letter will be considerably shorter. My professional activities and my education give me a notion of the full life cycle of software, including documentation. However, I can also be partly wrong. In addition, I tend to believe that in the open societies all decisions should be made together, and if we can not agree with standards, we need to change them. Therefore, I would like to offer a discussion on how we should further proceed with the Help development. I'm not a native English speaker, so please ask questions, if I can not deliver my idea clearly enough. I would like to get your opinion as well, if possible. This is my vision of the structure of Calc function articles. 1. Article title Title of the article should be brief, but give enough information about what will be discussed below. This should include specific terms, which allow the user to know exactly that he sees the page he/she wants. For example, if the page is called TIME, one can not be sure that he reads the right page until he start reading some further text on the page. Although it seems a trifle, it may take time and cause some user irritability if he mistakenly hits an unneeded article. Our goal as the documentation team is to help the user find solutions to his issues, but without brain temperature increase. This situation will arise when we use the TIME, DATE, DAY, TRANSPOSE, STYLE, and others for an article title. For example, in my opinion, instead of title just “TIME” we must provide “TIME function”. 2. Brief description of why this function is needed, and what it returns This item is most needed for the people who have experience of using Calc, but did not use this particular function. Therefore, information about what the function does and what results are returned should be included. For example (IMCOS function): In theory (but not in Calc), a complex number can be represented as a special type of number (e.g. looks like Scientific format in Calc) or as an array of two cells (e.g. looks like a result of some array functions in Calc). But in Calc complex number is returned as a string “a+bi” in one cell. You can check it with the help of the ISNONTEXT function. If we write in the Help article only that the function returns the cosine of a complex number, but don't say in which form, then the user, who does not use this function, may not know that the result is returned as a string, because it is unusual for Calc. That's why, the type of the returned value must be clearly specified, especially if this can be misinterpreted. 3. Way of working for complex functions This item is required for functions, whose work may vary depending on the implementation. A user needs to understand how it works, because in some situations it can provide a surprise result. This is especially important in sciences such as sociology, economics, marketing, statistics, which, depending on the theory and the school (e.g. West vs. Soviet school statistics [3]), use various mathematical formulas, though the name can be the same or similar. If we do not believe in the uniqueness, we have to clarify this for the user. Otherwise, the Help will only confuse the user. In addition, this item enables quick understanding for mathematically literate users. 4. Compliance with the ODF In fact, I believe that it is necessary to specify both compliance and incompatibility with the standard. Actually at present, some of the functions are not only incompatible with the standard, but there is a decision by developers not to lead them into compliance. [4] It is not an important reason why the function can be incompatible with the standard. The fact is important itself. For example, AGGREGATE and INFO functions. The first is not included in the ODF standard. The second supports only 5 categories of the 10 required. [5] 5. Syntax I would like to point out the common mistake that occurs even in proprietary software Help, when an optional separator of an argument includes an obligatory argument. If a separator of arguments is optional, it must be isolated together with optional arguments. For example, MIN(Num_1 [; Num_2 [; Num_N ]]) =MIN(5) Returns 5, while =MIN(5;) Returns 0, because the second argument is implicitly specified and equal to zero. If a formula has many values for such arguments, it is possible that a user will not understand this mistake and get a wrong result. 6. Detailed explanation of each input
