[Foresight-i18n] Localisation and Documentation

[Thilo Pfennig]

Hi, I like to criticize the way the documentation was produced. The
result is very good, but what ios lacking is:

* No documentation in the wiki on where the package is, how this
should be handled or edited
* No reuse or update of existing package foresight-documentation

see also http://wiki.foresightlinux.com/confluence/display/docs/Developing+Documentation

Nobody will be able to help in any way or translate the documentation
which is essential as you should look at this documentation as if it
would be in a foresign language for you.

So as Paul seems toi have the best insight I suggest that a
documentation team is formed and that its documented how one should
work with the documentation. We also have to consider how we deal with
inconsistences between wiki and hardcoded documentation. I also
suggest to follow the version of foresight with the release numbers of
documentation just like I did with foresight-documentation. Then we
always know for which release the documentation was built.
Why is the package version 0.0.2 while the guide itself tells its version 0.9?


I also think that its a bit confusing for users to have two helps
entries - one in system and one in applications->Foresight . I think
the best thing would be to have a commons start page for GNOME and
Foresight help.

We could also work on upstream GNOMEs help partly and integrate it
nicely into ours. In german the  guides are old as of 2.14. The thing
is that a user will propably open the help that he sees first. Maybe
an option would be to have a first login script and to open the help
he should see and also add a help button on the panel.

I also dont think that people who have installed Foresight or are
using it are interested first how they could download. I would put
this at the end rather.

I would also rename the chapters from "Banshee Music Player" to "Play
Music" or from "F-Spot Photo Manager" to "Organize and import your
photos". Get the idea? The user might not yet know what the
applications names are - but he knows what he wants to do.

>From the Foresight concept I also would put  "Post Installation
Configuration" rather under andvanced topics.


I think these are the things people are most interested:

1. Where am I? What is Foresight?
2. I want to get in the internet (this means either the computer
network just works or people will have to configure wireless cards. It
would be nice to have a list of supported cards (maybe just a long CSV
list?) Otherwise we ant to link to a page where the user gets a hint:
Your card is not supported? Your options are: a,b,c. And a checklist
that makes sense.
3. Ok he can do internet than he propably wants to use the web. We
could maybe provide a link to a nice success page on our web server
from the guide.
4. Email, which means Evolution maybe? We can here as well as for
other apps link directly to the localized documentations. Why
frustrate the user with only few english explanations when there is a
fully localized german documentation for the latest Evo? ... We dont
really have to do everything from scratch! Thats whats really cool
about the GNOME help
5. Maybe the graphics card - but 90% of the new users wont need that.
Configuring the graphics card should be part of the documentation -
but also make this one point
"Video Card Binary Drivers" and "Compiz / GL Enabled Desktop" tell a
grandpa nothing. We need to think from their perspective. For fine
graining we can provide more detailed instructions but sometimes
telling people to press the "Auto" button on the LCD is rather what
hey want and need.
6. Play Music - yeah handling of MP3 players etc. We need to tell
people how they can sync with that - which is not mentioned.  The
thing is: its ok if Banshee asks them where their music is but we
rather would want to tell them how they get music. We should also tell
them abotu what to do if they have no sound. Lets also make pages
where we say: "Congratulations - you now have sound" or so.
---
 People need positive feedback. Nobody reads manuals really. But if
they do (and its important that they find it then) they demand answers
to the questions they have. The questions come from following
problems:

 * No internet - how can I fix?
 * No windows network - how can I fix?
 * How do I get my photos on my computer?
 * I have no sound - what can I do - they really wont care about
banshee if they dont have no sound at all!!
 * etc.

I am writing this because I think that there is a big danger in just
listing the great things that are availaible - this is rather OUR
view. In that sense the new GNOME Release notes are not great, because
they focus on what is new. You might like to say that this is
important - but really it is not for many people. So people like to
import photos in every GNOME or Foresight release. They like if its is
nicer - and its ok to note whats new about the dialogs - but also
still - if there digital camera is not supported they wont give a damn
about how nice it would be if they cant get it running. My father
still cant import photos automatically (Olympus) and he would never
read the release notes - or if he would read he would expect to read
that his problems are fixed.

Not sure if I made my point clear. What I was trying to say is that
the documentation needs to meet the user expectations. I think the
windows documentation sucks too -but what I like as an idea is that
the documentation helps in solving problems.

We also need to get much better in communicating to each other and/or
document what and how we do things. many parts of the development
process are still intransparent which means that help from newcomers
is highly unlikely. So documenting how things are done and how to help
is the most important thing. I have experienced that the documentation
in the wiki has helped a great deal in helping users who want to build
their own packages. But I must say that 95% of how things are done is
neither documented nor does anybody talks about it. You rather are
being told what you did wrong.

I also like to suggest that we are doing a public session on package
creation and handling conary via IRC and maybe also with Gobby. I have
helped numerous users making their first steps - but I am not very
knowledgeable. I think if Antonio or KenVAndine or somebody else would
be demonstrating by an example on how to do things and maybe also that
we build together a recipe that one user wants to build we would all
learn a lot. Such sessions more regular (once a month) would increase
quality of packages and help those who can do packages to take more
responsibilities and take tasks from the core Gnomers.

The thing is that i do understand that many do not have much time and
have to do a lot - but the truth is that this is because of the
documentation and because there are too few people that know enough to
be really helpful. And at some point those sessions could be made by
more people and also there could be more than one session a month. We
could also make those session for specific problems like Wireless or
graphics. This could also help to get as much feedback as possible so
we can fix documentation or even fix a package if we have 3 people
sharing the same problem and we are able to track down the root cause.

Sorry for the long text. i could noit stop myself. ;-)

Thilo
cu in irc.

-- 
Thilo Pfennig
http://issues.foresightlinux.org/confluence/x/R