RE: [Webware-devel] Webware documentation

[Geoffrey T. <gta...@na...>]

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:ia...@co...]
> 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
> 
>