Re: Bounty: Live Documentation Editing

[Murray Cumming <murrayc murrayc com>]

On Thu, 2005-06-02 at 00:00 -0400, Eduardo M. Gonzalez wrote:
> I'm also interested in (and applied for) that bounty.  Which is the main
> problem with bounties, that they discourage collaboration.

You'll get better results with collaboration and therefore more chance
of success. 

> The difference between the DocBook wiki and the goal of Live
> Documentation is that there's no integration between the documentation
> and the source-code.  I'm planning on being able to parse C/C++/C#/Java
> files that use doxygen

Doxygen can generate XML instead of just HTML, so this might be useful,
particularly with some kind of xml-diff tool.

However, most GNOME documentation doesn't use Doxygen. gtkmm does, but
GTK+ uses gtk-doc for reference documentation.

And we mostly use DocBook for high-level documentation.

>  and generating diff files so that it'd be easy
> for developers to keep their code up to date with the documentation.
> Live Documentation needs to know about functions and objects, and be
> able to offer the developer more than just a wiki.  Adding a rating and
> comment system can provide the developer with valuable feedback for
> future versions of the library.  GNOME doesn't really have API
> designers, but this can make up for it.  
> 
> I have a lot of ideas for this project but I want to ask the developers
> what they would be interested in.  For example I was thinking about
> adding a forum for every section so that people with questions could ask
> right there, but I think mailing-lists are a better place for that.
> 
> My current ideas are:
> Links to GNOME ViewCVS
> Discussion board
> Notes (tips/tricks/bug workarounds)
> Tags (incomplete, depreciated)
> Translations
> Importing from Python docstrings
> 
> (Note that all of these things are separate from the actual
> documentation and will be either tabs or links.  So they will not show
> up when you export the documentation to DocBook, or diff.)
> 
> I'll see if I can get a quick mock-up  by this weekend based on
> everyones ideas.
> 
> On Wed, 2005-06-01 at 17:36 -0400, Corey Woodworth wrote:
> > Is there any more specefic information about what parts are
> > particularly under par?
> > 
> > On 6/1/05, Corey Burger <corey burger gmail com> wrote:
> > > On 6/1/05, Simos Xenitellis <simos74 gmx net> wrote:
> > > > Dorsk wrote:
> > > >
> > > > >Hey, I would like some more information regarding this bounty.  Does
> > > > >anyone have relevant information?  Thanks in advance.
> > > > >
> > > > >Description:
> > > > > Implement a live web-based wiki-like editor that allows generation of
> > > > >content that can be rolled back into our documentation. Allows users
> > > > >to contribute annotations and additions to documentation (e.g. can add
> > > > >documentation to an undocumented function), save it. Other people
> > > > >visiting the page will see your additions to the documentation, and
> > > > >the maintainer of the module can extract the addition and trivially
> > > > >roll it into the official documentation source.
> > > > >
> > > > >
> > > > It looks like http://doc-book.sourceforge.net/homepage/
> > > > could be of help here. Care to contact the author for this?
> > > >
> > > > Simos
> > > 
> > > The Ubuntu doc team evaluted this tool and found it wanting. Sean
> > > Wheller can give more information regarding it.
> > > 
> > > If we can involve the author, sounds like a good target.
> > > 
> > > Another good target is extending Mediawiki to do it.
> > > 
> > > Corey
> > > _______________________________________________
> > > gnome-doc-list mailing list
> > > gnome-doc-list gnome org
> > > http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> > >
> > _______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > http://mail.gnome.org/mailman/listinfo/gnome-doc-list
-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com