[Foresight-i18n] Re: [Foresight-devel] Localisation and Documentation

[Paul Cutler]

Thilo, thanks for the feedback.  Some comments below:

On 9/25/07, Thilo Pfennig <thilopfennig at foresightlinux.org> wrote:
> 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 agree with the above, especially forming a Docs team.  I think this
will be part of the Developer meeting next week where we start talking
about more formalized sub-teams, and this should absolutely be one of
them.  Once the team is formed, we can get the wiki up and running.
This can include how to use the Mercurial repository for editing and
translations, etc.

> 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.

Agreed.  I was never able to find the correct XML files that the GNOME
User Guide uses to integrate in to the Yelp home page that initially
comes up.  I need to reach out to the GNOME docs team.
>
> 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'm not sure I agree.  When I first started using Gentoo many years
ago, one of the few reasons I switched because of their amazing
documentation.  I remember printing out their manual and reading it
before I downloaded it.  One of the (few) good things about Docbook is
it's ability to export to many different formats, including HTML,
which we could in theory put in the website.
>
> 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.

I agree - I remember editing the chapter names after being almost done
from "Banshee" to "Banshee Music Manager" for this reason.  I think
the Userguide needs additional content before we make this change, to
include things like importing photos or digital media players  before
that happens though.  The Userguide today is focused on the
application itself, not the experience.
>
> >From the Foresight concept I also would put  "Post Installation
> Configuration" rather under andvanced topics.
>

The most common question asked in IRC post installation is video card
setup.  There are a few different options we could choose from here.

> 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 think you bring up some really interesting use cases and how it ties
to documentation.  As I mentioned above, if we re-write the Userguide
to focus on use cases or the experience of how someone uses their PC,
there is a lot more documentation that could be written.  I'm very
open to it, and would love the help.  The first draft of the Userguide
available now was written in about 6-8 weeks, and could use a lot of
help.  I'm no Docbook expert at all, in fact a real writer would
probably laugh at some of the hacks I probably used to get it to look
and feel the way I wanted.  It should be setup for Localization (I
think) in the repo.

The goal is to include the Userguide in 2.0 and keep it evolving from
the wiki to the HG repo.  It will need updates in the short term for
PackageKit and Post Installation configuration (just off the top of
head) for the 2.0 release.  I am very open to major changes, and would
love any help that anyone wants to contribute.

<snip>

I think you bring up some really good questions that I don't know we
have all the answers to yet (that I edited out above).  After talking
to Ken, I'm trying to play a more active role in helping project
manage Foresight.  That includes the developer meeting in IRC next
week, which will be a good forum to start discussing these kind of
things.  This will include forming sub-teams such as Docs, Development
such as PackageKit, Packaging, Bugs and more.  These teams will have
dedicated wiki pages where we can start to document how and what they
work on, as well as scheduling sprints to tackle specific goals and
tasks.

There is no question though if we don't communicate more consistently,
including through email and the wiki in addition to IRC, we won't be
as successful as we all want Foresight to be.

More to come soon.

Paul Cutler
pcutler at foresightlinux.org