Hi Alex,
Alex Thurgood wrote:
Frank Peters wrote:
Hi again,
You don't need a masters in English for writing documentation. Most
of the folks I met in Lyon have a sufficient knowledge of the
language to at least write some raw material that can be brought
into shape by native language review. Your stylistic and didactical
skills are probably more crititical.
Yes, I would tend to agree, but I have found that people in general
often feel intimidated to contribute for two main reasons :
- lack of self-confidence
- having to deal with rules and regulations before even starting
Whilst it is a "necessary evil" to have at least some formalism, this is
one of the major hurdles for many, who feel that it is already an
immense effort for them to come up with something that others might find
useful (linked to the self-confidence issue, of course). If they have to
overcome these hurdles before they even start, all but the most
confident or hardy tend to say "someone else will undoubtedly provide
for that, and I shall make do with my own personal help notes". This is
not particular to any given language, but I know that Tony Galmiche,
Sophie and Laurent Godard all regularly go to lengths to explain how to
submit documentation, and I believe (though Sophie may correct me if I'm
wrong) that in the French project, we even have some form of online
documentation explaining that (but I can't pinpoint it right now). By
hurdles, I mean of course, reading and understanding the JCA, or the PDL
or the CC, using a particular style or template format.
Well, I agree with the most important part of what you said, however, I
think that the "group" or "community" is important here. The more the FR
documentation project is active, the more new people come to join it (so
thanks a lot to Jean-François who has attracted several new contributors
:-). The fact that the work in progress (meaning reviewing, criticizing,
discussing) is visible for all and open to all is very encouraging for
new comers because they are able to see that they won't be left alone
during their participation.
Template and guidelines are not negative for all, they could help also
contributors to feel secured by this framework. When I write articles
for magazines, I feel always better if they provide me with a template.
Obviously, one can always invite people to just write stuff and then
have it put into form afterwards, but in that case, the burden then gets
shifted onto others who already do a lot for the community, and may not
necessarily have the time or the inclination to want to do so on a
permanent basis.
+1 :-)
On OOoCon I briefly discussed this dilemma with some folks
from Germany when we were thinking about the next conference
location. The fact that there is no English native language community
(or particularly a US/North America community) keeps all projects
in English more separate resulting in less momentum (bold
thesis that is?).
I would tend to agree, and the fact that there is no specific user
"community" in the sense that we understand it for the N-L groups has
always surprised me somewhat, but it is, I suppose, inevitable.
I agree
It would be interesting to know, when this feedback was given. We are
aware of this issue and were and still are working very hard to move
OLH to concise how to instructions and task based help topics.
Well, the feedback I had from my users was highly critical when we first
switched to OOo 1.1.x, and understandably so. Things have been much
improved IMHO with version 2.x, but only last week, one of my members of
staff said they typed in a word (I don't remember which one now) in the
search index and nothing came out of it. When I showed them where to
find the things they were looking for, they turned to me and said, "how
many people do you know like me who would've typed in the keywords you
just entered ?" All of this being with respect to the French version of
course. To be honest, I had to concede defeat on this point. I was
thinking of a similar example with my 13 year old daughter looking to
change the colour of the font in a text she had just typed. I told her
glibly : "Look in the help" So she did, but didn't find immediately what
she was looking for. Obviously, teenagers (or at least my kids !!!)
don't like spending a lot of effort looking for something. We actually
had to spend about 2 minutes trying to find the bit she was interested
in, and that was with me helping her. When we did find the page in
question, it did not appear at the top, but rather we had to scroll down
under the preceding paragraphs (relating to the character properties
dialog box) to find the relevant passage. This is just one example (well
2, if you include my employee's problems ;-) ).
The FR OLH had a lot of inconsistency in it and wrong examples, and so
on. We have done a complete reviewing those last month and I think that
the most important part will be in 2.1 (provided somebody takes what Ian
won't have the time to correct, however I didn't check what is remaining).
As a professional trainer, I found that most of the time, the "how-to
search/use the online help" is something that is ignore during the
training session. So we (me not ;-) have also to teach our user how to
use this help and make them understand how it works, because after being
trained in general, they feel happy with it.
For a feedback about the content, I think that some part are to
technical or the examples to complicated for real newbies.
This will be the second pass I would like our project to give to the
OLH, a reviewing with newbies eyes :-)
We need to find the right balance (which is always hard to find :-)
I agree, and it will never be easy.
and one way is to get feedback from the users that don't feel
comfortable with the OLH as it is. Unfortunately, this is rarely
the case. This is one thing I wanted to promote at OOoCon. The easiest
way in contributing to OLH is to yell out what you don't like
(and occasionally tell us what you do like, too, so we don't get
overly frustrated :-)
Yes, the positive feedback rarely gets mentioned :-)
Frank I'll collect the positive feedback for you, because I have had lot
of them :-)
Maybe one way
around this would be to divide the help up into basic and advanced
tasks. Of course, we would still be faced with the problem of deciding
what goes where :-(, but we could in that case maybe organise a poll
amongst users on the various lists to try and determine that.
The idea to link to external documentation is very good. Sometime, it's
only some rephrasing that is needed. But I agree with a 2 level
approach, a kind of "going further", or a way to switch to an advanced
help when you reach the advanced level of use.
Do the IZists know about that?
Hmm, don't know, but I guess most of the leads know. Personally, I hate
IZ for documentation, I find it really does clutter up quickly, but then
others may have a different opinion.
I think that every body agree about IZ being the most difficult tool for
a non English speaker. We already had several thoughts about simplified
inteface, translation or localization, etc. But the fact that this is a
tool dedicated to developers work make the task difficult. Currently the
only way to go is in adding a human interface between users and IZ (I
mean most to the time the NLC project leads or long-time contributors).
I guess docs doesn't need to use all processes that development
engineering uses. We have different requirements so that's probably
fine. BTW: Where can I read about the Docs&Files system?
Off-hand, I wouldn't know, sorry :-(
Now this is probably something for the writers at Sun here in Hamburg,
we are close to most of the developers, so it should be easier for us
to establish some sort of information flow.
Laurent has mentioned the Extensions project, which is taking off, and
the dba project has produced its own useful documentation to a certain
extent, but I don't know about the others.
You have documentations every where in the project, just visit the
doc&files part of the core projects, or just use the search
functionality on the site using the "all projects" option, you'll be
surprised by the richness of our site :-)unfortunately not reachable for
every body.
Kind regards
Sophie
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
