gnucash-docs

[Linas Vepstas]

On Tue, Nov 26, 2002 at 09:21:13PM -0800, Chris Lyttle was heard to remark:
> 
> Then we started about july discussing a release before years end. I knew
> I'd never complete carol's guide by then but that also the docs that did
> exist we a mismash of stuff that was just added in bits and pieces. I
> set out to write a completely new coherent help that people using 1.8
> could use not for all the background account concepts of GnuCash but
> just to answer 'how do I do this task?' which is what most of us use
> help for. 

Yeah, we never distinguished "help" from "manual", it took too 
much work...

> I was out of work at the end of august so had a lot of free
> time to work on this, and now its almost done.

specifically the "help" part.  Which is oriented toward accomplishing 
specific tasks.

Seems to me that there is still room in the world for a manual,
which does have an overview of principles, and talks about things 
more broadly/generally, and is not task-oriented, but more
concept-oriented.  More of an accounting-principles type style.

I am no longer clear on how this overlaps with carol's stuff.  
I thought her stuff was part concepts, part tasks.

Either way, is there any left-over material that *could* be mangled 
into a manual? (in  theory, by someone, without having to write
much new text?)

I still want a 'manual' that can be posted on-line at least.
and it would be nice to have the manual also be accessible
from gnucash directly, in addition to the help.


> So forward to the 1.7.2 release. I decided then as I would get the new
> help done I wanted to disable to old help from the build. This also had
> the advantage of reducing the tarball size by 10MB. 

 good.

> I basically edited
> the makefiles to remove all the sgml docs from the build apart from 2,
> guide.sgml and help.sgml which are just placeholder pages.

as above, I'd still like an overview manual.  My software usage patterns
are that I almost never read the detailed 'how-to-do-this' documentation
(too boring), but like to luxuriate in the overview (the more it is
written in the style of PBS 'nova'/history channel/'american
experience', the more I like it). 
 
> Now we have a choice moving forward, to cut the translated docs so that
> perhaps someone using GnuCash will be encouraged to write new ones or
> translate my new help to their language or to include the old docs in
> the hope that someone will see the english docs are better and proceed
> to translate. 

I kind prefer the latter. 

For example: message catalogs: gnucash-1.4 had more translations than
1.6 ever did (or 1.7 does, to this day).  Some of the translations that
were cut never came back.  (ukrainian is one that comes to mind).

> Either way its going to be a lot of work for whoever does
> the translation. 

Yes, we know that, but the naive translators do not.  They think "well,
someone has started this, and all I need to do is fix it up a bit".  Its
a lot easier to take that approach than to think "gulp. Doing a
translation means starting at square 1 for a very big job". 

Its more of a psychological thing: the translator feels more comfortable
because someones already started the job.  Laid the foundation.   Its
like any community-service thing: easier to pitch in to some existing
scheme, than to champion a brand new one.  Even if, after a while, 
you realize that you are doing most of the work.

>  People can still
> get translations from a 1.6 installation and copy them to the right
> place.

virtually everybody will be too lazy to do that.  New releases get
anywhere from 10K to 30K downloads (actually, I think even more for 
the more recent ones), and that's not counting whatever ships on
redhat/suse/connectiva cdroms, etc.    Not only will individuals
not make the copy, but I also fear that the package maintainers who work
at redhat/suse/connectiva (and debian) will not bother to assemble 
a suitable euro version.  And so the gazillion-whatever european
gnucash users will have no native-lang documnetation , as opposed
to old, crappy documentation.  I say "something is better than nothing,"
in this case.


--linas

-- 
pub  1024D/01045933 2001-02-01 Linas Vepstas (Labas!) <linas@linas.org>
PGP Key fingerprint = 8305 2521 6000 0B5E 8984  3F54 64A9 9A82 0104 5933