[Gtk-sharp-list] Full documentation by 1.0

[Brian Kerrick Nickel]

On Tue, 2004-06-22 at 15:55 -0400, Miguel de Icaza wrote:
> I have been trying to push for documentation for at least a year now,
> with various degrees of success.  We even got Monodoc to have a
> built-in editing facility so folks could contribute without having to
> learn too much about CVS, but it has only resulted in marginal
> contributions.

I think part of the problem is that monodoc's editing function can be
frustrating to use. I've experienced the following problems with it:
 * Ctrl-C doesn't work in edit mode. Select/Middle=click pasting doesn't
   work too well either.
 * If you close before submitting your contributions, it won't recognize
   the changes (or something, that's as far as I can tell)
 * No spell checker.
 * The buttons aren't really clear and not HIGified.
 * No explanation that you need to use different letters to reference
   members, fields, classes, et al.
 * No spell checking.
 * No documentation/guidelines as to how documentation should look,
   sentence structure, brevity, descriptions, et al.
 * No undo/redo.
 * Crashed after I submitted contributions the first time. (Is this
  fixed?)
I think you get the idea, it's just really uncomfortable to use, with
some unexpected behaviors. I'll try my hand at cleaning it up, but here
is what I'd like to see:
 * Use GtkSourceView
 * Use GtkSpell (Is there a managed version of this?)
 * Tab completion in <see> (If possible)
 * Beautification.
 * Clipboard working.
 * Simple guideline found in help menu.
 * A way to mark something like "In progress" so if I'm contemplating
   documenting something I can click a button and see: "Documentation in
   progress by Miguel." or something.
 * Outside of contributing, there should be a function somewhere:
"Download latest documentation" that downloads a snapshot of the
documentation so you it's not dependent on any software releases.

As for getting people interested in documenting, I think the best thing
would be to make a big deal about it. Register monodoc.com, create a
monodoc-list (does one exist?), have Mono Love Days, have "documentation
goals" and "documentation competitions", have a "Top contributors list
with contribution percentages, etc. I think if it's exciting enough,
easy enough, and gratifying enough, people will be willing to
contribute.

> Could I convince you to contribute to the Gdk.Pixdata classes that you
> just learned how to use the hard way?
I submitted contributions which I'll update when the new API is
finalized. Looking at CVS it looks like it's pretty good except what I
commented on in the other thread.

- Brian