I didn't set out to be a documentor...

So I've been doing a "daily doc" for php-gtk2. I was on IRC one night and christian weiske was whining about wanting people to help with documentation. Now, I'd never done anything with docbook before (and php/php-gtk's bastardized docbook is even more "fun" than the original) and I was afraid.

So he mentioned that someone could download the skeletons from view cvs , fill in the descriptions, and send it to the list. Enter my inner dialouge "That doesn't sound so bad...  I should stop complaining and help...because I say that to my kids all the time." And because I have an ulterior motive (C people should be writing C not docs... I want 2.10 done someday so I can have thinks like the gtkassistant :) I decided "I can do that..." even though I've done enough gtk coding to fit in a thimble.. But hey, I was an english major in college. Writing I can do. (As everyone's eyes bleed from my grammar on this site...)

I'd always stayed away from writing docs because I thought you needed to know the code before you could explain it to others. However, although php-gtk2 is not documented real well (yet) Gtk+ and other gtk wrappers (perl, python, even ruby) have some great docs, so I had somewhere to start from, and it's been...interesting.

I'm not doing a "full" documentation job at the moment, because REAL documentation would have LOTS of examples, something I'm not sure I'm ready to jump into quite yet. But I am filling in the basic descriptions for classes, methods, constructors, and learning a lot about gtk in general in the process. And I figure if I can get some of the basic work done, people with more knowledge and experience can flesh out the docs, write examples (although I'll probably move into that once descriptions are done), and most importantly, get the actual implementation done for php-gtk2. I just HATE wanting to use a method and finding it hasn't been implemented yet :)

In the meantime, I watch the documentation and implementation numbers creep upward and wonder when scintilla, sourceview, and mozembed gtk extensions will work with php-gtk (and hope someone takes the time to make them work on windows...)

My biggest wish right now is to get a spellchecker working with php-gtk2. Now there is gtkspell but it appears to be lacking development. PyGTK has gtkspell in GnomePythonExtras but according to the mailing list gtkspell2 doesn't use gobject which makes wrapping it difficult (and my C knowledge is at about the hello world level)
That and if php-gtk2 allows custom widgets (and even if it doesn't with some nasty workarounds) - php already has aspell/pspell support (that works on windows) - theoretically I could get my own spellchecker working that way.

Now I could just teach myself some more C (oh fun...) and write the stuff I'd like, but quite frankly I love the ease and simplicity of php.  And I could move to another language (say python, which appears to have some really fabulous gtk support) - but I'm inordinately fond of my braces and semicolons and procedural programming (hence why ruby smells like rotten skunk to my poor eyes...it's a metaphor people).  So I'll keep documenting, and some day I'll move on to writing examples, and maybe soon that magic 100% will appear and someone with some C knowledge will have time to wrap/teach me how to wrap gtkspell (or get custom widgets working so I can roll my own).

What? A girl can dream!

In the meantime?  Writer is getting fun to use.  You can make chapters now and I should commit this stuff to cvs but I need to pick up my kids and sweep the floor and make the frosting for my husbands chocolate cake that I just baked for his birthday and...

Yes, I am supermom, hear me roar.


Be the first to write a comment!

Post a Reply