[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gimp-developer
Subject:    [Gimp-developer] contributing to gimp-help-2
From:       "William Skaggs" <weskaggs () primate ! ucdavis ! edu>
Date:       2004-09-15 16:06:45
Message-ID: 200409150906.AA86376950 () primate ! ucdavis ! edu
[Download RAW message or body]

This is for anybody interested in contributing to the Gimp Help 2 /
User Manual.

Current status:  

We have a good prospect of having a high-quality help
package, for at least English and Chinese, ready by the time Gimp 2.2
is released (in 2-3 months), and would like to push toward that
goal.  At this point the great majority of topics have been
implemented in English, although a few important ones remain; only
about a dozen of the help-id's defined by the GIMP core remain unbound.
However, many of the descriptions are very sketchy, having been
written in a hurry by people who were not native English speakers.  

(You can see the current state of the documentation at
http://docs.gimp.org.) 

Thus, there are two great needs:

1) For English, work on the existing descriptions to make them more
   complete and more helpful.  

2) Translate (or write original material) for other languages.
   Currently English and Chinese are moving along well, German and
   French have quite a bit of material, and Swedish is barely started.
   Other translations do not exist, but this doesn't mean you can't
   start one, even if you don't plan to write very much:  the longest
   book begins with a single sentence.

Even so, if you feel that the Manual is missing something that it
needs, and you would like to write it, that is definitely welcome --
although in this case you might be advised to mention it first on
gimp-docs@lists.xcf.berkeley.edu. 

Concerning proofreading, the need for this will grow as we approach
the endpoint, but currently for many sections it would take more time
to describe what is missing than actually to write the material.
Nevertheless, if you spot any out-and-out errors, we would definitely
like to know about them.

How to contribute:

The Help material is written in Docbook XML, and the most independent
way for you to work would be to check out the source files from CVS
and edit the XML.  But this is not necessary, and unless you are
planning to put a great many hours into it, not even a good idea.  You
can make a very valuable contribution by writing simple plain text and
giving directions for where it belongs.  There are at least three ways
you could submit such material:

1) Email it to gimp-docs@lists.xcf.berkeley.edu.

2) Email it to me, weskaggs@primate.ucdavis.edu

3) Put it on the wiki, at http://wiki.gimp.org/gimp/GimpDocs, in the
   Whiteboard section.  If you do this, please send email to let us
   know that it exists and you're ready for us to look at it.

You don't need to ask permission or "check out" a topic, although if
you want to discuss it first, you're welcome to.  We're not going to
try to allocate sections to people because it happens very commonly
that people get excited and make commitments that they find themselves
unable to keep.  The best approach is to submit material in small
increments, as soon as you write it, and keep your eye on
http://docs.gimp.org/en/, which is never more than a few days out of
date.

Although we are aiming to align the Manual with GIMP 2.2, you should
not hesitate to contribute if you happen to be working with GIMP 2.0
(but not GIMP 1.2 or earlier!).  Most things work very nearly the
same, and it is much easier for us to make a few minor corrections
than to write material from scratch.

The purpose of the Help is to be helpful.  Material can be oriented
either toward beginners or more advanced users.  Ideally, it can be
written in such a way that every type of user finds out what she needs
to know, without being obstructed too much by material intended for
other levels of users.  This is often challenging, but possible. 

Translating:

If you want to write material in French or German, please mention your
plans on gimp-docs@lists.xcf.berkeley.edu, so that the maintainers for
those languages will know what you are doing.  The same applies to
Chinese, where the translation is moving so rapidly that you are
likely to conflict with Cai Qian if you don't discuss your plans with
him first.

If you want to write for another language, you can just do it.  The
material you write should be in UTF-8 encoding.  Because we won't be
able to understand it, you will need to help us figure out where it
should go:  the easiest way to do this is to submit each translated
item side-by-side with the English material it corresponds to.  You
are not committed to translate any more than you want to, but if you
translate something, it would be nice to translate the headings above
it (chapter, section, etc) so that people will be able to find it.

Graphics:

Pictures are hard to handle efficiently.  The ones we have been using
are in PNG format, and we make efforts to keep the pictures, and file
sizes, as small as possible without compromising their functions.  We
try to avoid including language-specific elements unless necessary.
For screenshots, we try to use the most basic window themes. 

If you can manage without adding graphics, that's obviously the
easiest thing to deal with.  Next easiest is if you can find a place
on the web to put your graphics, and give links to them, so that we
don't need to waste disk space by putting into permanent repositories
things that will need to be altered.

What we don't need:

1) Advice.  It just leads to arguments, which discourage people and
   keep them from working.

2) Criticism, except to point out absolute errors.  We already know
   that lots of things need improving.  We will want criticism, but
   later. 

3) Tutorials, except for basic methods or central concepts.  For
   special tricks, in most cases the web is a better place.

4) Graphic tutorials.  They can be very beautiful, but are
   untranslatable and unmaintainable.

5) Material that is informative without being helpful to users.
   Sometimes it is helpful to know the technical background for
   something, sometimes not.

6) Material borrowed from other sources.  In some cases we may be able
   to use such material, but we absolutely need to discuss it first,
   know where it comes from, and be completely clear that the
   copyright makes us completely free to use it in any way we want.

7) Expressions of opinion that will be offensive to some people.  The
   idea is to be helpful, not to cheerlead.

Finally:

To be completely clear:  if you contribute something, you are implicitly
giving us the right to use it in any way we want.  There is, of course,
no guarantee that we will be able to use your contribution at all,
though we will definitely try to respect your efforts.

Thanks for any help that you can give, and please don't hesitate
to ask questions if anything is unclear.

 

 
______________ ______________ ______________ ______________
Sent via the KillerWebMail system at primate.ucdavis.edu


 
                   
_______________________________________________
Gimp-developer mailing list
Gimp-developer@lists.xcf.berkeley.edu
http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
[prev in list] [next in list] [prev in thread] [next in thread]