I kinda like just using HTML with simple styles for documentation, as we are now. It works, it's easy to edit by hand, and it's just one less thing to learn.
You're right, it's the content that's lacking, not the formatting. I don't really care one way or the other if we split it up or leave it in large pages. - Geoff > -----Original Message----- > From: Ian Bicking [mailto:ianb@;colorstudy.com] > Sent: Thursday, October 24, 2002 3:42 AM > To: Webware devel > Cc: Webware discuss > Subject: [Webware-devel] Webware documentation > > > 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 ------------------------------------------------------- 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
