Re: Annotated online documentation

[Owen Taylor <otaylor redhat com>]

[ Cc'ing gtk-doc list ]

On Wed, 2005-02-23 at 13:53 +0100, Murray Cumming wrote:
> I think it would be nifty if people could add comments to the online
> documentation. Obviously we'd rather have patches to the
> documentation/source, put people don't often go to that trouble after
> they have discovered something - they need code changes to be submitted
> but documentation changes are not essential to them personally. However,
> they'll make comments immediately if it's easy, and maintainers can then
> make their own changes.
> 
> One gtkmm user suggested phpnotes, which you can see demoed here:
> http://www.murrayc.com/temp/gtkmm_book_with_comments/html/ch13s02.php
> 
> It was very easy to add the php code to the html with xsl:
> http://bugzilla.gnome.org/attachment.cgi?id=37773&action=view
> 
> It's the first time I've heard of it, and I don't know about any similar
> systems. I have the usual dislike php. Any thoughts?

Thoughts ...

 - Without looking at implementation, I suspect it would be relatively
   easy to add something like --enable-phpnotes to GTK_DOC_CHECK()
   and gtk-doc.make. (Which turned on a XSL stylesheet parameter,
   perhaps.)
 
 - One big problem is making sure that comments get preserved if
   documentation is moved around and across versions of documentation.

 - You probably do want some way of attaching comments to individual
   functions rather than the entire page. I suspect some sort of 
   CSS layer/Javascript thing might be needed to be useful without
   too much clutter. (Icons you can click on to get a popup or
   something like that.)

 - I think user comments are a bit of a bad idea without an active
   editorial process. Useful information needs to be moved into the
   real docs. Wrong information needs to be deleted.

   I've not been 100% impressed with the PHP comments; they are
   useful at times. At other times, it's just a noisy discussion
   between people who don't really understand what's going on.

 - You'd need to figure out the license situation for comments and
   sample code in the comments and make it pretty explicit to people
   submitting comments.

Regards,
						Owen