Re: Annotated online documentation

[Murray Cumming <murrayc murrayc com>]

On Fri, 2005-02-25 at 14:27 -0500, Owen Taylor wrote:
> [ 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.

I think it uses IDs. You can specify section IDs in docbook that stay
the same. I'm not sure how it would work in gtk-doc.

>  - 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.)

Yes.

>  - 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.

Yes. This phpwebnotes thing does allow easy moderation. If I use it for
gtkmm.org then I will actively update the original documentation and
ruthlessly delete nonsense. I think any commented documentation would
need a dedicated moderator. It's work.

>    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.

I think moderation could help there.

>  - 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.

Yeah, some little disclaimer should do that.

-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com