![[TEST] Document Foundation Community](https://communitytest.documentfoundation.org/images/discourse-logo-sketch.png){kind=logo}
Hi 
Nabble allows people to edit posts but they don't show up with any of the other ways of viewing the lists so it's best to avoid it. I sometimes correct my typos there. I think it's best to avoid setting rules that people have to read before posting because that sort of thing has led to flame-wars on this list.
Regards from
Tom
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.
So it has two aspects, the helpful one and the - how you put it - "sucking"
one.
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.
Generalizations like "the help is bad, rather look into User Guides" are less
helpfull.
User Guides have their uniqe role in helping people to understand certain
principles / concepts, as they offer much more space for detailed & redundant
descriptions. However they are "secondary products" often produced by "mere
users" and thus there are two major "gaps" within them: the time gap, i.e.
they "follow" development with a certain delay and, the accuracy gap, i.e.
they can miss certain aspects or details or functions, just because they have
been simply overseen or forgotten by the original writer of the guide.
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.
(And, yes, there are the bad aspects, too. They need improvement, of course.)
Regards,
Nino
+1
For many users seem easier to ask in the net than read the built-in help, when often the answers are there, even with samples.
And in this program like in others, IMHO, the first is at least a quick read of the built-in help to get a panoramic view, so you can have a basic acknowledgement over can be done and how.
But the sign of these times is that everyone wants things done for yesterday for free and effortless.
Miguel Ángel
In the old days, the answer to this was RTFM; but nowadays, with political
correctness and all....
Cheers,
Ron.
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
Sod political correctness....ooops !! 
Alex
Hi
Hopefully none of the devs write-up documentation for the features they write in!
1. It's a different skill-set. We, well i, would prefer to see devs able to fly through coding and keep on going rather than worrying that if they do the code then they have chores to do afterwards as punishment. Ok, so some devs are superb at both.
2. Translating from pure geek into something comprehensible takes a lot of effort which could probably be best spent exploring the new feature and seeing if it really works for a not-quite-so-geeky person.
3. "mere users" are often superb at documentation, especially people that are new to the project. The aim of documentation is to write for new people, or people that are new to the aspect they are reading-up about. Who understands them better than other new people that have just managed to battle their way through whatever the chapter is about. It would be a huge help to have new people proof-read chapters before they get published to the wiki or at least before they get added to the official LO website. Usually one person writes, then another proof-reads (bit of a simplification). Unfortunately such people quickly become quite skilled because they learn a lot quite fast so we constantly need other newer people to join the docs team.
Dan is a total star and does a lot of work in a lot of lists and his work on the first 2 chapters of the Base Guide inspired other people to get on with translating the Base part of the Faq and that led to a lot of interesting discussions on the user list. A couple of people from the user list then seemed interested in getting involved as devs to build-up Base a bit. It's the first time i have heard of documentation being a driving force in an OpenSource project!
http://wiki.documentfoundation.org/Faq#Base
Sorry about the generalisation about the in-built help. It is good and useful because it's so easy to access but the chap already had that bit and i wanted to point out another better way of getting help. Sometimes something is so close to be perfect but there are just not enough resources to put the icing on the cake and that leads to a lot of frustration and angst. If it was really horrible then people wouldn't care so much and they would just avoid it.
Regards from
Tom
<snip />
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.
<snip />
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"
<snip />
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
helpful.
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.
<snip />
Hi
+1
BUT i like it when people ask a question and are then able to post the answer back to the list. Or where answering the question is simply a case of pointing them at documentation and copy&pasting the relevant section into the answer.
I would definitely prefer people to ask in here rather than fret and worry and possibly give up just because they don't yet know their way around the help systems!
Regards from
Tom
Hi
Hey, that wasn't me. It's not what i said. On the other hand my email !'client' does suck except for work stuff where it seems to produce exactly what people want.
Regards from
Tom
<snip />
Let's face it, the built-in help system sucks
<snip />