I'm willing to try reST or an XML format. One thing I do like about HTML with styles is that anyone can contribute to the documentation with just their favorite text editor and a web browser. Whatever solution we use should be very easy to install and use, and I'd like to see a "documentation how-to" guide that tells you what to download and how to get started writing docs within 5 minutes.
- Geoff > -----Original Message----- > From: Ian Bicking [mailto:ianb@;colorstudy.com] > Sent: Thursday, October 24, 2002 12:44 PM > To: Geoffrey Talvola > Cc: Webware devel; Webware discuss > Subject: RE: [Webware-devel] Webware documentation > > > On Thu, 2002-10-24 at 10:37, Geoffrey Talvola wrote: > > 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. > > Yeah, reST is little weird to learn thoroughly, though the basic > structure is simple enough. But I really found while doing the > documentation for FFK and SQLObject that using it made the entire > experience much more pleasant -- it still takes a long time to write > documentation, but it felt a bit less burdensome. Previously > for FFK I > had styled it after the Webware documentation, and there was a certain > relief I felt deleting all the HTML markup. I also found > navigating the > source (for updating) to be much easier -- reST is entirely > readable as > text, while HTML is not so great, and updating is our real problem. > > There are some annoying parts about reST -- for one thing > there doesn't > seem to be any HTML escape, so you can't include arbitrary > HTML in your > page (though of course arbitrary HTML source is easy enough). > I like to > be able to do that for some examples, though I'm more likely > to include > source than rendered HTML. Or you can do like Aaron did, and use > screenshots -- but if I hate writing with all the markup, I *really* > hate dealing with screenshots. It would be neat to have an automatic > screenshot generator, though... maybe using htmldoc. But that's an > aside. > > 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://ads.sourceforge.net/cgi-bin/redirect.pl?sunm0003en _______________________________________________ Webware-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/webware-devel
