[izpack-devel] Changes in ShortcutPanel / UserInputPanel

[Elmar Grom]

Hi Julien,

sure, I agree with you about the problem. I was managing development teams
for long enough to not have the illusion any more that this will change in a
fundamental way. I just hope folks will take this seriously enough so that
they at least care. That is why I offer to write the text, as long as folks
send me e-mail about their changes, along with the necessary information.
The format we use at any given time should not matter, as this is mostly a
'mechanical' issue. 

Just to be clear on this also: I really appreciate what Fabrice is doing.
Unfortunately, I don't think many of the contributors appreciate the fact
that they are short changing his efforts by making the content inaccurate or
incomplete.

If we would still work with the graphical Frontend then documentation might
not be quite as important, since it would be more apparent from the UI
elements what features are available. The fact that everything must be
written in the script makes documentation indispensable. 

I find it sad that so many contributors are willing to invest their precious
time to make IzPack better and in the end practically nobody even knows that
their contributions even exist, just because those are not documented.

Every now and then I toy with the idea of approaching a publisher to see if
they would be willing to publish a book on IzPack, but then I wonder if it
would be possible at all to collect all of the necessary background
information. At least perhaps we could try to launch a documentation update
project. A starting point could be your suggestion to work through the
commits and identify things that need to be documented. Then we can contact
the developers to request the necessary information.

If someone can perform the first task, I would be willing to do the actual
writing.

	Elmar


-----Original Message-----
From: izpack-devel-admin at berlios.de [mailto:izpack-devel-admin at berlios.de]
On Behalf Of julien at izforge.com
Sent: Wednesday, July 12, 2006 10:10 PM
To: izpack-devel at berlios.de
Subject: Re: [izpack-devel] Changes in ShortcutPanel / UserInputPanel

Hi Elmar,

I understand your frustration, especially when you have rigorous quality
standards (which is a very good thing anyway, and I am the first one to
enjoy that). The decision to switch the documentation from LaTeX to XHTML
(then soon DocBook) had been made on common consensus. Fabrice is devoting
a lot of his precious time on this task, and should be thanked for that.

Yet, we have this problem of documentation, which is probably larger than
the IzPack project. Generally speaking, developers don't like writing
documentation. That's the sad yet true truth. The fact that we are in a
transition period over the documentation format is probably another factor
that discourages people of ensuring that new features are documented.

I suggest the following:
- current developers *must* make sure that they include documentation with
new features they add
- current developers *must* check that code from external contributors
comes along with documentation before they perform the commit.

The good thing is that we can check the commits on izpack-changes. Since
SVN makes atomic commits, we can see when a changeset is missing docs ;-)

Also, it would be good that Fabrice tells us which format (XHTML or
DocBook) should be used right now for the documentation. We should also
think about cleaning the folders in src/, since there are still the LaTeX,
XHTML and DocBook files.

Cheers

_______________________________________________
izpack-devel mailing list
izpack-devel at lists.berlios.de
http://lists.berlios.de/mailman/listinfo/izpack-devel