Re: New documentation

Am 29.04.2006 um 18:37 schrieb Dominik Wa=DFenhoven:

> I'm new to the jurabib developer team, and as the position that Jens
> gave me for the sourceforge.net project indicates ("Doc Writer"), I
> would like to contribute by re-writing the jurabib documentation.

Great.
I had also proposed that I could help updating the documentation, but=20=20
did not do anything until now. So I'll be glad to contribute ...

> We all know that the documentation needs (maybe more than) a
> face-lifting, because it is an accumulation of worthwile information,
> but has lost its stringent structure. Thus, I want to give a first
> outline of a new structure for the documentation, which is derived=20=20
> from
> the original one. Any suggestions are appreciated!

Sounds good after a short view.

Another thing we should do ASAP is a collection of the things that=20=20
are missing in the documentation today.

To start:

- All the 0.61 changes are not documented

- The Translator field is not described

- Maybe a lot of other things ...

> Also, any suggestions for handling the files in the SVN repository are
> appreciated. I think the now existing documentation should stay in the
> repository as long as the new one is not nearly completed, but it=20=20
> would
> be easier to write the new documentation from scratch; so I thought of
> two possibilities:
>
> a) jbendoc.tex and jbgerdoc.tex stay as they are, and the new
> documentation files get new names (though I had no good ideas until=20=20
> now,
> at least none with only 8 characters...)
>
> b) The now existing files will be renamed to jbendoc.old and
> jbgerdoc.old, and the new ones get the names jbendoc.tex and
> jbgerdoc.tex (which could lead to confusion).

c) keep old and new names the same, and create a branch for the doc=20=20
update in the SVN.

But probably b) is the best solution.

In the end, the PDFs have to get the same names as today.
The SVN is intended to keep development versions of the files, so it=20=20
wasn't a problem if they are not finished.

A small problem might occur if jurabib 0.61 is released before the=20=20
new documentation is finished, but it should be easy to manually add=20=20
the old version of the doc to the relase package.

How do you want to start?

Would it make sense to implement the new structure in a quick-and-=20
dirty way by just moving around the paragraphs? That might be helpful=20=20
to see if the new structure works.

Best regards,
Matthias



--=20
Matthias Damm
[email protected]
PGP key: http://macpla.net/MatthiasDamm.asc
PGP fingerprint: CED3 6074 7F7D 3148 C6F3  DFF2 05FF 3A0B 0D12 4D41



=20
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/jurabib-developer/

<*> To unsubscribe from this group, send an email to:
    [email protected]

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/
=20