inline...
--- Mike Cannon-Brookes <[EMAIL PROTECTED]> wrote:
> I agree that the documentation should certainly be
> available out of the box.
>
> My experience is that, however, one needs to make
> documentation as simple as
> possible to write.
>
I agree somewhat. An easy form of sharing tips,
kluges, etc. is valuable but IMO, the quality of such
written documentation isn't quite up to par for
something like a Users Guide (which is what we're
discussing ATM). Keep the wikiweb as a resource for
sharing amongst users, etc. but separate the official
docs.
> Look at how much documentation and knowledge the
> Wiki has created compared
> to how much doco we had from people 'getting off
> their ass to write XML'.
>
Quantity != Quality. Do we want a user's guide that
looks like 10 authors took turns writing each chapter
of a novel? Imagine the formatting and written style.
This might work for a cookbook sort of document but
that's not the topic of discussion.
>
> Shipping this is another question though. I'd think
> (as the amount of
> documentation we have is relatively little!) we
> could pull it off the Wiki
> into another format at regular intervals, to make a
> PDF or HTML doc?
>
And here's the biggest problem in your proposal as I
see it. You've just created another task/role for the
project. Who is going to surf the wiki to pull off new
submissions to add to a distributable doc?
IMO, the user's guide/startup docs should be a static
document. It is not a dynamic beast which grows like a
knowledge base. Obviously the docs will evolve as the
project evolves (added functionality, refactoring,
deprecation, etc), but it should not require the
constant addition of new material. It should document
the framework and provide steps on how to get it
built/install/configured. If a user comes up with a
fancy new way of doing something, I don't feel it
warrants inclusion in the User Guide.
> Cheers,
> Mike
>
> PS That said, he who wants to write the
> documentation gets to choose how it
> is done.
>
Agreed. Ken has offered to do work and after
discussion has even compromised on rendering html for
a dist build. If we're concerned with the complexity
of others submitting docs after such a mechanism
(xml/xslt) is in place, then hopefully Ken can do a
simple how-to on XSLT.
As long as the build process supports the rendering of
html/pdf from the xml/xsl, it gets my vote. If it
requires the user to install a cocoon, etc. piece to
run it, then I'd have to say no due to complexity.
-Wayland Chan
__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com
-------------------------------------------------------
This sf.net email is sponsored by:
With Great Power, Comes Great Responsibility
Learn to use your power at OSDN's High Performance Computing Channel
http://hpc.devchannel.org/
_______________________________________________
Opensymphony-webwork mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork
