Sean,
You've given us a lot to think about.
I'll be mostly offline until January 3, but I'll be thihking about thi
and I hope to have some answers for you then.
Thanks for your enthusiastic participation!
Regards,
jrs
On Dec 30, 2005, at 4:00 PM, Sean Wheller wrote:
On Friday 30 December 2005 16:26, John Sundman wrote:
The sources to the documentation are in (all paths relative to the top
lps dirctory):
<snip what="Description of documentation src locations"/>
OK, it's as I thought, the doc system is a propriety solution
XHTML-like in
source.
While the current system works, I think that getting to know it and
enhance
upon it will be prohibitive for most people. When I say most people, I
take
it that the willing author will have some technical knowledge or would
not be
editing the XHTML sources in the first place.
With few people understanding how it is hung together, it will also be
a
bottleneck in an open development environment. Sticking to a standard
will
open the opportunity for writing docs and enhancing the processing
system.
It would, IMHO, be a better solution to adopt Docbook as the standard
format.
The DTD is documented and so are the stylesheets. I see some of the
processing tool chain is already in SVN. As most of the project is
Java I
would say the following environment would fit right in:
Ant (or GNU Make)
Saxon (enabled extensions)
FOP (enabled extensions)
Docbook DTD
Docbook XSL
DITA may also be a solution. Although I am not yet happy to use it on
production systems, if the project is willing to eat dog food, then
so am
I :-)
I see lots of duplication in content and the need to repurpose content
for
different readers. There are a number of techniques we can use to help
overcome the problems.
If I was to think of a way forward, I would suggest we do a test run.
Implement a short, but reasonably complex, document into docbook and
build
the batch processing and custom layer systems for it (PDF, HTML
(single page
and chunked)). That way we can get to grips with the difficulties
together.
The reference manual can be made allot easier to maintain and develop
if we
modularize the documentation into components and normalize across the
doc
system.
The risk. Can we document the next release and complete the new doc
system
before the next release? If we have enough time. I estimate that we
can do
the transformation to the new system by end of January. What is the
release
schedule?
Let's start the new year with a challenge :-)
Happy New Year.
--
Sean Wheller
Technical Author
[EMAIL PROTECTED]
+27-84-854-9408
http://www.inwords.co.za
_______________________________________________
Laszlo-dev mailing list
[email protected]
http://www.openlaszlo.org/mailman/listinfo/laszlo-dev
