[libreoffice-users] Re: Built-in Help vs. User Guides

Le 04/05/12 13:46, Nino Novak a écrit :

Hi Nino,


> But OTOH, built-in Help is *very* helpful in certain situations IMHO. So, if 
> one is looking for the exact syntax of a regex or if one wants to learn about 
> how to use a calc function, it is first choice. 

I would agree with you there, but still I regret the days of the more
detailed built-in help content that used to be present in StarOffice and
OpenOffice.org 1.x. It was at least generally more useful than the
current laconic style.

> So it has two aspects, the helpful one and the - how you put it - "sucking" 
> one. 

Agreed.

> So what we have to do is, 
> * looking where we can improve the bad aspects
> * trying to keep up the valuable aspects
> * make people aware of *both* sides and help them adjusting their expectations 
> to the reality: that will maximize their benefit.

Agreed, but how many of the developers actually write up the new
features they put in, with an explanation of how to use them ? In my
experience they don't (on the whole) and they certainly don't write the
help files. And yes, I've seen the odd developer wiki page here and
there, but that is no substitute for a competent help entry.

It is, in fact, dependent on "mere users" to play around with the
features until they suss them out (I rather fear that is the case in
main). Certainly, from what Dan Lewis has had to go through with
preparing the Base Guide, it would appear that many of the entries one
would expect a built-in help to have, were simply not there. In that
case, the Base Guide will virtually be a drop in replacement for the
built-in help.


> Generalizations like "the help is bad, rather look into User Guides" are less 
> helpfull.

Agreed, unless true, if a user can't find what they are looking for
after a search in the built-in help, then where do they turn to ? The
documentation list and guides maintained by the users.

Hmm, now let me think, what was one of the new features in 3.5 ?
Postgresql native driver support. OK, so stick in "postgresql" in the
index of the built-in help, what do you get ? Zilch. Try again in the
Search tab, zilch. Bash your head against a brick wall and then go and
trawl the postgresql developer documentation to try and glean the likely
connection parameters - as a "want-to-try-it-out" user with 3 hours to
kill, yeah sure, why not, but kinda defeats the object of having
built-in help.



> Therefore, I'd rather have us teaching people the difference between the 
> possibilities of getting help than playing them off against each other and 
> thus confusing people.

I'd rather we be able to create/modify/adapt the built-in help system in
an easy and collaborative way that empowers and encourages people to
contribute. As far as I know, not even the SDK/ODK documentation can be
built on all OSes by default without fiddling (thanks to the change to
doxygen), so for example, on Mac, not even the developer documentation
is provided (to be more specific, the option has to be switched off by
default, else the build fails).

This may seem like a rant, it isn't, but if this project wants people to
help improve the inline documentation, then it needs to find a way to
let them contribute easily, safe in the knowledge that their changes
will be integrated swiftly. For the moment, by far the easiest way is
through the user produced documentation guides project, but as you
correctly point out, that is not the same as the inline help, and yet,
it is rapidly becoming more and more like that.


Alex


-- 
For unsubscribe instructions e-mail to: users+help@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/users/
All messages sent to this list will be publicly archived and cannot be deleted