Issue 71289 - Calc: Overall display of Function Help
Summary: Calc: Overall display of Function Help
Status: CLOSED FIXED
Alias: None
Product: documentation
Classification: Unclassified
Component: Online help (show other issues)
Version: 680m187
Hardware: All All
: P3 Trivial (vote)
Target Milestone: 4.x
Assignee: Uwe Fischer
QA Contact: issues@documentation
URL:
Keywords:
: 67425 (view as issue list)
Depends on:
Blocks:
 
Reported: 2006-11-07 11:28 UTC by Uwe Fischer
Modified: 2017-05-20 10:24 UTC (History)
2 users (show)

See Also:
Issue Type: ENHANCEMENT
Latest Confirmation in: ---
Developer Difficulty: ---


Attachments
example of new main page for Mathematical Functions in Help (12.82 KB, application/vnd.oasis.opendocument.text)
2006-11-07 11:30 UTC, Uwe Fischer
no flags Details
Improved Maths functions Help content (46.60 KB, application/vnd.oasis.opendocument.text)
2006-12-08 08:43 UTC, drking
no flags Details

Note You need to log in before you can comment on or make changes to this issue.
Description Uwe Fischer 2006-11-07 11:28:37 UTC
posted by mail from drking:

The issue that would cause the most work for you (!) is to do with the current
display of function help in a long list. A good example is DSUM, where to look
at "Joe's birthday party" (required to understand the example) needs 8 mouse
clicks - and 8 clicks to get back to the example.
...
There are two ways round this:
Repeat "Joe's birthday party" table for each example - yuk - makes the text very
long, or
Put DSUM on another page

I wonder if you would consider that? It would have to apply to all functions -
so that each function had its own page - but this would be good, because then
when the user looked at the Database Functions he would be able to see all the
possible functions in a manageable list, and quickly choose between them.

I've mocked up an example for the Maths functions in the file "math-fn.odt".
Simply having a list of the available functions, rather than having to scroll
furiously, would be pretty good I think. Especially for those function
categories (eg Stat1, Stat2...) already on more than one page. It's done this
way in Excel (not that that should sway you!). You'll see that I've cut the
explanatory text so it sits on one line, so the user has just enough information
to decide whether to investigate further.
...
Another advantage is that it would allow the inclusion of "See also" texts for
all function and possible expansion of examples, without making the existing
function lists/categories even longer.
Comment 1 Uwe Fischer 2006-11-07 11:30:47 UTC
Created attachment 40392 [details]
example of new main page for Mathematical Functions in Help
Comment 2 Uwe Fischer 2006-12-01 14:05:54 UTC
Now following issue 70462 the Calc functions pages are no longer listed
alphabetically. We can order contents to be alphabetically in english, but some
localized versions use translated function names, and alphabetical order is not
the best one anyhow.
We will rework all Calc functions help pages. New main pages should be added as
follows:
main_functions.xhp is the page with a general description and links to the
categories pages.
main_{categoryname}.xhp are pages with one line descriptions and links to the
subpages. These links are ordered within categories by function groups, so that
all functions you would want to find in a "see also" section are inside one file
(as much as possible). Links to related functions in other categories also must
be added.
Comment 3 drking 2006-12-08 08:40:56 UTC
The attached file MathsFn1.odt is a contribtution hoping to move this a bit
further forward, by refining and improving the Calc Help system texts. It
relates to the Maths functions. Specific improvements are:
- I’ve included the index.
- I’ve used a uniform methodology and layout for each function text. The first
line is now always pithy, so it can be read quickly, with  the main explanation
later. I’ve applied styles consistently.
- I’ve corrected a number of errors in the existing text.
- I’ve substantially revised all the text for clarity.
- I’ve included more (and clearer) examples, to try to answer users’ questions.
- I’ve added numerous links to other topics, to help the user find what he/she
needs.
- I’ve added a couple of new explanatory topics - most notably “Conditional
Counting and Summation”, which is intended to be the bees knees on this subject.
- I’ve included a function that is implemented but had never been documented.

The file is in Writer format, because ordinary mortals cannot yet usefully alter
the help sources files. However it looks fairly authentic and the links work, so
it gives a good idea of how it would look in Help.

I noted that you'll be grouping functions non-alphabetically - seems very sensible.

Comments on usefulness, content etc would be very welcome. Typing this lot into
the Help source files will need some considerable effort from the help team, so
it would be good to know that it is what is wanted.
Comment 4 drking 2006-12-08 08:43:35 UTC
Created attachment 41230 [details]
Improved Maths functions Help content
Comment 5 Uwe Fischer 2006-12-11 10:56:32 UTC
*** Issue 67425 has been marked as a duplicate of this issue. ***
Comment 6 Uwe Fischer 2007-01-11 12:38:56 UTC
changed target
Comment 7 Uwe Fischer 2007-02-19 15:42:32 UTC
Inserted most of the  changes in CWS hcshared08. No "See also..." links yet
because we first must revise the file structure (some files are just too big)
Comment 8 drking 2007-03-05 19:13:21 UTC
Many thanks for this.

The issue is nowhere near FIXED though.
*Having "see also" links is a vital part of this - Excel Help had this in 1997.
*There are several other categories of functions to be revised - I've postponed 
work until we get the Maths category up properly


Also, last time I looked Ooo1.1.5 when used as a Help editor was unable to show 
function parameters consistently in a single typeface - needed if the result is 
to look professional. Has that been overcome?

Thanks for making a start...

Comment 9 Uwe Fischer 2007-03-06 08:17:20 UTC
removed this from hcshared08. Will continue to work on the Calc files as time allows
Comment 10 drking 2007-12-06 09:01:15 UTC
Hi Uwe

I am now using the wiki to upload improved function descriptions:

http://wiki.services.openoffice.org/wiki/Documentation/How_Tos/Calc:_Functions_l
isted_by_category

It will take time to complete. I will link it properly to the main HowTo index 
when I've uploaded more descriptions. I hope it can be transferred when the 
entire Application help is converted to the wiki, but in the meantime it seems 
a useful start.

Comment 11 Uwe Fischer 2007-12-06 09:26:16 UTC
That is good news, David. Have a look at
http://wiki.services.openoffice.org/wiki/Calc/ODFF_Implementation and the
schedule linked from there. We'll have to apply some major changes to the Calc
function pages in the application help. Some for OOo 3, some later.
Comment 12 Uwe Fischer 2009-12-04 14:13:11 UTC
In issue 106917 the Calc function files got changed to the same structure as in
http://wiki.services.openoffice.org/wiki/Documentation/How_Tos/Calc:_Functions_listed_by_category

Now we can insert "See also" links to the new files. CWS hccalc01, target OOo 3.3
Comment 13 Uwe Fischer 2009-12-11 08:16:32 UTC
fixed in cws hccalc01
Comment 14 Uwe Fischer 2009-12-11 13:06:05 UTC
verified in CWS
Comment 15 Uwe Fischer 2010-06-01 14:44:02 UTC
Due to problems with high word count and high number of files, the CWS hccalc01
was shifted to OOo 3.4