I forgot to mention, the documentation tools need to work on Windows. Not everyone uses Linux to work with Webware.
- Geoff > -----Original Message----- > From: Geoffrey Talvola > Sent: Thursday, October 24, 2002 12:54 PM > To: 'Ian Bicking' > Cc: Webware devel; Webware discuss > Subject: RE: [Webware-devel] Webware documentation > > > 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
