----- Original Message ----- From: "Tom Jordahl" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Tuesday, November 05, 2002 1:56 PM Subject: RE: Ok... pet peeve
> > I am not a big fan of moving away from HTML. > > I have really good tools that I can use (<plug>Can you say Macromedia Dreamweaver MX?</plug>) to write up docs with little fuss. I can say macromedia dreamweaver and its clear as I edit the source by hand that someone was using gui tools. But I can also say 'LaTeX' and 'PDF' are valid output formats. I also think framemake scales better, even though I dont actually own a copy. Failings of the current documentation -I dont know how much is correct -It's missing big things: configuration, using seralizers, how to use Axis.jar in your own webapp -The user guide is one big long file. OK for printing, not for browsing In its favour, the architecture and integration guides are good, and there are plenty of pictures. we dont want to lose that. But we need more end user docs, in a way that end users can navigate around. I'd rather see a split of the user guide into separate topics, one per page, maybe all under docs\userguide. But that is the presentation, we may still want to represent it in XML for ease of generating multiple output types. As an example, the docs/ant docs are autogenerated via XML and velocity. The velocity tool in either DVSL or anakia formats may be a good way for the generation of static content from the XML Templates.
