The Webware documentation isn't in very good shape, as it hasn't been actively updated in a while.
Anyway, I've been writing lots of documentation lately, and I've been using reStructuredText (http://docutils.sourceforge.net/rst.html). It's worked pretty well for me -- the output looks decent, but more importantly it's comfortable to write. Keeping the documentation up-to-date is the most essential part. In some way we should also split the documentation up for the different parts -- Application, Adapters, Page, ... maybe all in the same file, or a couple files... I'm not sure. Anyway, we could then really try to keep it up to date with any changes to the code. What do people think about reST? Docbook is spiffier, but I dread actually writing it, and we're content-poor, not formating-poor. Another option is utilizing doc strings for more. I'm not really sold on it, but if someone feels more comfortable about generating real documentation that way it might be a good idea. But generated documentation like that just never looks quite right to me. It lacks useful structure, it's bound to methods, and the documentation seems to put trivial methods on par with important methods. But I'll look at docutils more closely... though it's at an early stage. But I would be open to tweaking docutils to make it work... Actually, I guess my real issue is that inline documentation doesn't distinguish between user interfaces and internal interfaces -- particularly when those internal interfaces are not entirely internal, like methods that you may wish to override in a subclass, but which you wouldn't call directly. And when you look at classes like HTTPServlet and Page, it only confuses people to present all that, when a document on servlets (in all forms) would be much more helpful. Anyway, those are some of my thoughts. I'd like to clean up a lot of the documentation for 0.8. Ian ------------------------------------------------------- This sf.net email is sponsored by: Influence the future of Java(TM) technology. Join the Java Community Process(SM) (JCP(SM)) program now. http://ad.doubleclick.net/clk;4729346;7592162;s?http://www.sun.com/javavote _______________________________________________ Webware-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/webware-devel
