Re: My prosposal: Usability and the footnote function

[James E. Lang-2]

I am a big fan of OOo. My remarks below are not intended to be an attack on
anyone. I have included personal examples of problems I have had with the OOo
documentation. I suppose I am straying from the original topic. If so, I'm
truly sorry.

--On Monday, October 05, 2009 09:25:54 AM +0200 Uwe Fischer
<Uwe.Fischer@...> wrote:

> Hi,
>
> On 10/04/09 23:08, jonathon wrote:
>> Robert Derman wrote:
>>
>>> OOo should include a pair of manuals in the download package, either in PDF
>>> or ODF formats, the presence of which would be made obvious the first time
>>> you opened the suite.
>
> I would not object in making the presence of the installed Help more obvious.
> At present, many users first refer to some mailing lists, forums, or other
> sources to get help, and most often they will return a "read the installed
> Help - it's all there what you're asking"

The cited response on the lists antagonizes some people. We ask our question
because we cannot _find_ the information within the installed Help. It may well
be there but we don't all use the right magic words to look it up.

> Users who don't find the installed Help will possibly not find the enclosed
> manuals, too.

I find the installed Help just fine. It's just that I often don't find what I
need when I look there. I also find it near impossible to find specific
information that I need from any list or forum archives. I'm sure I'm not alone
so please be tolerant of people like me.

>> a)  I'd suggest both PDF and ODF formats.  The latter so that the user
>> can add notes, documentation , etc that they (the individual) thinks
>> is necessary/useful.

Personally useful, that is. The notes etc. may not be useful for everyone.

>> The former, because it can be  read regardless of platform, or wehther or
>> not OOo has been installed;

These ideas sound good. Some of the online documentation is available in these
formats. I'd also suggest adding "Manuals" or "Guides" to the menu bar or to
the installed Help menu to assist in accessing the files that Jonathon is
suggesting and also any online documentation.

>> b) I'd suggest a copy of all of the documentation that OOoAuthors has
>> produced, for that specific version of OOo. Since that documentation
>> lags behind OOo  releases, it might be more useful

Are you saying that the OOoAuthors documentation is more up to date? Where is
it to be found?

> So what is wrong with the main documentation page at
> http://wiki.services.openoffice.org/wiki/Documentation
> Everything you asked is there, and much more. And every user, including
> yourself, can add to that information pool.

I, for one, have no experience in updating a wiki page. I also would not rely
too strongly on a wiki page that I had updated. It would contain information
that I have learned by experience and it would be as accurate as I could make
it but we all think we have learned certain things that simply are not so.

I would also add that not all of us are as savvy as you are. Not knowing where
to look is a big part of the problem. As for myself, online manuals in the
format of the documents I have examined from the Documentation wiki are not
easily searched and therefor it is very frustrating to try to use them.

I concur that there is a lot of documentation available at the OOo web sites.
It just is not easily found or used by the novice user who needs it the most. I
also note that the Calc 3.x User Guide is "draft" and the Draw 3.x is "coming
soon." Part of the problem is, of course, that in particular in the open source
paradigm the "sexy" part is updating the code while the documentation is often
relegated to the status of the ignored step child. This is not just a problem
for OOo.

>> On Sun, Oct 4, 2009 at 15:54, Gene Young  wrote:
>>
>>>  In what way is the help "totally inadequate"?
>>
>> a) Minor, but significant for the affected population groups:   Not
>> all localizations have translated the help file into the local
>> patoise.

The online documentation is no better in this regard. It is stated to be
English language documentation.

>> b) Content is the help file is not applicable to the current version of OOo;

This should never be the case but unfortunately it is way too often. And I'm
not just speaking of OOo in this regard.

> please give at least one example.
>
>> c) Functions in OOo are not described in the help file.
>
> see above

I'm not sure what you mean by that response.

>> d)  Help files are not indexed by the expected word/phrase.

Documentation that has a table of contents and an index and that resides in a
single file or web page would be a significant improvement so that it can be
searched from end to end.

>> Ideally, every word/phrase.concept  found in the help files, and./or
>> documentation for WordPerfect Office, MSO,  GnomeOffice, KOffice, Red
>> Office, GoogleOffice, and Symphony will be found in the help file,
>> with a cross reference to the OOo name;

I'm sure that would be a major undertaking.

> please provide a list, we will happily add that information to the installed
> Help.

Again, the installed Help is only one tool for enhancing one's experience with
any product.

I possess different levels of expertise with various facets of OOo. As such I
need to use documentation differently. I'm sure I'm not the Lone Ranger in this
regard.

I have no idea what can be done with either Draw or Math.

Until I looked at the main documentation page referenced in your message, I had
no idea where to look to start learning how to construct an Impress "document."

I have used Writer to create simple text documents with fonts, columns, etc.
but if I were a student having to write a term paper with footnotes or
endnotes, or if I were an author trying to write a book or manual, I would not
know where to start. I also could not insert tables or illustrations in such
documents. I've seen help given on the users mailing list to people who are
trying to do these things and thought, "that's interesting," but the ones who
asked the questions were already so far ahead of me that I have no clue how to
get to the point where they are having their troubles.

On the other hand, I'm a relatively advanced user of Calc. In general, the
installed Help is all I need _now_ to utilize Calc though I recently learned
how to define print ranges which I had seen used but which were black magic to
me. I thought I was looking at protected fields instead of data that was
outside all print ranges. I still don't know how to write macros.

I still have no idea how to make use of OOo through the external application
interface (command line call with the ability to modify the contents of a
spreadsheet, for example, via a script and to direct OOo to print selected
parts of the data and to save the revised document). I don't even know the
right words to use to name this functionality that I know exists. Thus I can't
find information as to how to utilize it.

You may think I'm digressing but these are examples of the issue that I
understand is being discussed. Documentation needs to be upgraded by people who
_know_ the product. Going to the local Borders etc. or to Amazon for books
about OOo is a lost cause. But looking online is not a whole lot better.

Thank you for bearing with me.

--
Jim


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-unsubscribe@...
For additional commands, e-mail: discuss-help@...

[Robert Derman-2]

James E. Lang wrote:

> I am a big fan of OOo. My remarks below are not intended to be an
> attack on
> anyone. I have included personal examples of problems I have had with
> the OOo
> documentation. I suppose I am straying from the original topic. If so,
> I'm
> truly sorry.
>
> --On Monday, October 05, 2009 09:25:54 AM +0200 Uwe Fischer
> <Uwe.Fischer@...> wrote:
>
>> Hi,
>>
>> On 10/04/09 23:08, jonathon wrote:
>>> Robert Derman wrote:
>>>
>>>> OOo should include a pair of manuals in the download package,
>>>> either in PDF
>>>> or ODF formats, the presence of which would be made obvious the
>>>> first time
>>>> you opened the suite.
>>
>> I would not object in making the presence of the installed Help more
>> obvious.
>> At present, many users first refer to some mailing lists, forums, or
>> other
>> sources to get help, and most often they will return a "read the
>> installed
>> Help - it's all there what you're asking"
>
> The cited response on the lists antagonizes some people. We ask our
> question
> because we cannot _find_ the information within the installed Help. It
> may well
> be there but we don't all use the right magic words to look it up.
>
>> Users who don't find the installed Help will possibly not find the
>> enclosed
>> manuals, too.
>
> I find the installed Help just fine. It's just that I often don't find
> what I
> need when I look there. I also find it near impossible to find specific
> information that I need from any list or forum archives. I'm sure I'm
> not alone
> so please be tolerant of people like me.
>
>>> a)  I'd suggest both PDF and ODF formats.  The latter so that the user
>>> can add notes, documentation , etc that they (the individual) thinks
>>> is necessary/useful.
>
> Personally useful, that is. The notes etc. may not be useful for
> everyone.
>
>>> The former, because it can be  read regardless of platform, or
>>> wehther or
>>> not OOo has been installed;
>
> These ideas sound good. Some of the online documentation is available
> in these
> formats. I'd also suggest adding "Manuals" or "Guides" to the menu bar
> or to
> the installed Help menu to assist in accessing the files that Jonathon is
> suggesting and also any online documentation.
>
>>> b) I'd suggest a copy of all of the documentation that OOoAuthors has
>>> produced, for that specific version of OOo. Since that documentation
>>> lags behind OOo  releases, it might be more useful
>
> Are you saying that the OOoAuthors documentation is more up to date?
> Where is
> it to be found?
>
>> So what is wrong with the main documentation page at
>> http://wiki.services.openoffice.org/wiki/Documentation
>> Everything you asked is there, and much more. And every user, including
>> yourself, can add to that information pool.
>
> I, for one, have no experience in updating a wiki page. I also would
> not rely
> too strongly on a wiki page that I had updated. It would contain
> information
> that I have learned by experience and it would be as accurate as I
> could make
> it but we all think we have learned certain things that simply are not
> so.
>
> I would also add that not all of us are as savvy as you are. Not
> knowing where
> to look is a big part of the problem. As for myself, online manuals in
> the
> format of the documents I have examined from the Documentation wiki
> are not
> easily searched and therefor it is very frustrating to try to use them.
>
> I concur that there is a lot of documentation available at the OOo web
> sites.
> It just is not easily found or used by the novice user who needs it
> the most. I
> also note that the Calc 3.x User Guide is "draft" and the Draw 3.x is
> "coming
> soon." Part of the problem is, of course, that in particular in the
> open source
> paradigm the "sexy" part is updating the code while the documentation
> is often
> relegated to the status of the ignored step child. This is not just a
> problem
> for OOo.
>
>>> On Sun, Oct 4, 2009 at 15:54, Gene Young  wrote:
>>>
>>>>  In what way is the help "totally inadequate"?
>>>
>>> a) Minor, but significant for the affected population groups:   Not
>>> all localizations have translated the help file into the local
>>> patoise.
>
> The online documentation is no better in this regard. It is stated to be
> English language documentation.
>
>>> b) Content is the help file is not applicable to the current version
>>> of OOo;
>
> This should never be the case but unfortunately it is way too often.
> And I'm
> not just speaking of OOo in this regard.
>
>> please give at least one example.
>>
>>> c) Functions in OOo are not described in the help file.
>>
>> see above
>
> I'm not sure what you mean by that response.
>
>>> d)  Help files are not indexed by the expected word/phrase.
>
> Documentation that has a table of contents and an index and that
> resides in a
> single file or web page would be a significant improvement so that it
> can be
> searched from end to end.
>
>>> Ideally, every word/phrase.concept  found in the help files, and./or
>>> documentation for WordPerfect Office, MSO,  GnomeOffice, KOffice, Red
>>> Office, GoogleOffice, and Symphony will be found in the help file,
>>> with a cross reference to the OOo name;
>
> I'm sure that would be a major undertaking.
>
>> please provide a list, we will happily add that information to the
>> installed
>> Help.
>
> Again, the installed Help is only one tool for enhancing one's
> experience with
> any product.
>
> I possess different levels of expertise with various facets of OOo. As
> such I
> need to use documentation differently. I'm sure I'm not the Lone
> Ranger in this
> regard.
>
> I have no idea what can be done with either Draw or Math.
>
> Until I looked at the main documentation page referenced in your
> message, I had
> no idea where to look to start learning how to construct an Impress
> "document."
>
> I have used Writer to create simple text documents with fonts,
> columns, etc.
> but if I were a student having to write a term paper with footnotes or
> endnotes, or if I were an author trying to write a book or manual, I
> would not
> know where to start. I also could not insert tables or illustrations
> in such
> documents. I've seen help given on the users mailing list to people
> who are
> trying to do these things and thought, "that's interesting," but the
> ones who
> asked the questions were already so far ahead of me that I have no
> clue how to
> get to the point where they are having their troubles.
>
> On the other hand, I'm a relatively advanced user of Calc. In general,
> the
> installed Help is all I need _now_ to utilize Calc though I recently
> learned
> how to define print ranges which I had seen used but which were black
> magic to
> me. I thought I was looking at protected fields instead of data that was
> outside all print ranges. I still don't know how to write macros.
>
> I still have no idea how to make use of OOo through the external
> application
> interface (command line call with the ability to modify the contents of a
> spreadsheet, for example, via a script and to direct OOo to print
> selected
> parts of the data and to save the revised document). I don't even know
> the
> right words to use to name this functionality that I know exists. Thus
> I can't
> find information as to how to utilize it.
>
> You may think I'm digressing but these are examples of the issue that I
> understand is being discussed. Documentation needs to be upgraded by
> people who
> _know_ the product. Going to the local Borders etc. or to Amazon for
> books
> about OOo is a lost cause. But looking online is not a whole lot better.
>
> Thank you for bearing with me.

One reason that I say that users manuals should be in the download
package is that tutorials are desperatly needed.  Help functions almost
NEVER include tutorials in OOo or any other program open source or
commercial.  That is why users manuals are a nessesity with any
productivity software package.

---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-unsubscribe@...
For additional commands, e-mail: discuss-help@...

[Uwe Fischer]

Hi,

please find some comments inline. I shortened the cited texts.


On 10/15/09 00:45, James E. Lang wrote:
> I am a big fan of OOo. My remarks below are not intended to be an attack on
> anyone. I have included personal examples of problems I have had with
> the OOo
> documentation. I suppose I am straying from the original topic. If so, I'm
> truly sorry.


this is the discuss mailing list, so let's discuss. Finding help is
certainly a usability issue, so the subject of this thread is almost right.

> I find the installed Help just fine. It's just that I often don't find
> what I
> need when I look there. I also find it near impossible to find specific
> information that I need from any list or forum archives. I'm sure I'm
> not alone
> so please be tolerant of people like me.
>
>>> a)  I'd suggest both PDF and ODF formats.  The latter so that the user
>>> can add notes, documentation , etc that they (the individual) thinks
>>> is necessary/useful.
>

may be adding personal notes to the installed Help is a good idea.
BTW, you can copy and paste every Help page to a text document. No
problem to create your own Help document over time.


> I, for one, have no experience in updating a wiki page. I also would not
> rely
> too strongly on a wiki page that I had updated. It would contain
> information
> that I have learned by experience and it would be as accurate as I could
> make
> it but we all think we have learned certain things that simply are not so.

I'm confident that the http://en.wikipedia.org/wiki/Swarm_intelligence 
will take care of any errors, let's say on the FAQ pages of the Wiki
http://wiki.services.openoffice.org/wiki/Documentation/FAQ
The Wiki would be empty if only perfect contributors were allowed.

>
> I would also add that not all of us are as savvy as you are. Not knowing
> where
> to look is a big part of the problem. As for myself, online manuals in the
> format of the documents I have examined from the Documentation wiki are not
> easily searched and therefor it is very frustrating to try to use them.
>
> I concur that there is a lot of documentation available at the OOo web
> sites.
> It just is not easily found or used by the novice user who needs it the
> most.

The normal Wiki search sucks. On the
http://wiki.services.openoffice.org/wiki/Documentation main page we have
two search boxes: the normal at top right, and a special one following
the text: "type here to search this Documentation Wiki". This uses a
local Google search and returns valid results.


Part of the problem is, of course, that in particular in the open
> source
> paradigm the "sexy" part is updating the code while the documentation is
> often
> relegated to the status of the ignored step child. This is not just a
> problem
> for OOo.
>

so get some experience how to update Wiki pages and do it. It is quite
easy, and the community would thank you.

>>> On Sun, Oct 4, 2009 at 15:54, Gene Young  wrote:
>>>
>>>>  In what way is the help "totally inadequate"?
>>>
>>> a) Minor, but significant for the affected population groups:   Not
>>> all localizations have translated the help file into the local
>>> patoise.
>
> The online documentation is no better in this regard. It is stated to be
> English language documentation.

?? the English versions of OOo get English Help. Many other language
versions get translated Help, while some still use the English Help at
this time, because of the high word count.

>
>>> b) Content is the help file is not applicable to the current version
>>> of OOo;
>
> This should never be the case but unfortunately it is way too often. And
> I'm
> not just speaking of OOo in this regard.
>
>> please give at least one example.
>>
>>> c) Functions in OOo are not described in the help file.
>>
>> see above
>
> I'm not sure what you mean by that response.

that response means that we want to know an example of "Functions in OOo
that are not described in Help" so that we can describe them in Help.


>
>>> d)  Help files are not indexed by the expected word/phrase.
>
> Documentation that has a table of contents and an index and that resides
> in a
> single file or web page would be a significant improvement so that it
> can be
> searched from end to end.
>

The installed Help has a table of contents and an index and a full text
search.


> Again, the installed Help is only one tool for enhancing one's
> experience with
> any product.
>

well, the installed Help is a reference for normal users how to use the
product. The installed Help doesn't intend to explain each and every
advanced use of the product: there are better media to do this, like the
Programmers Guide, the developers mailing lists, and more. The installed
Help links to these advanced resources wherever possible. Normally we
assume that someone who really wants to know the answer to some very
difficult questions will know how and where to find them. For example
here, on the mailing lists, or the forum, or using a web search machine.

The installed Help is not a tutorial and it is not a Beginners Guide to
OpenOffice.org, because those media already exist and are readily
available (most of them for free).


> ...Going to the local Borders etc. or to Amazon for books
> about OOo is a lost cause. But looking online is not a whole lot better.

when you go to amazon.com and enter Openoffice as search word, you'll
get 1505 hits this morning.
If you really need a printed manual, I personally would direct you to
the web stores that are run by the OpenOffice.org community or that are
affiliated with the community. One example is
http://openoffice.blogs.com/bookresources/


Uwe
--
   ufi@...  -  Technical Writer
   StarOffice - Sun Microsystems, Inc. - Hamburg, Germany
   http://documentation.openoffice.org/
   http://wiki.services.openoffice.org/wiki/Documentation
   http://blogs.sun.com/oootnt
   http://user.services.openoffice.org/en/forum

---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-unsubscribe@...
For additional commands, e-mail: discuss-help@...