Tuesday, April 25, 2006

The difficulty with documentation

I have found that understand things when given examples rather than prototype information on them. A perfect example is programming api's and such. I'll use the xfce api documentation to explain what I mean.

Picking something at random, let's look at the libxfce4panel reference manual. The second entry is listed as XfcePanelPlugin. The synopsis for it reads -

XfcePanelPlugin;
void (*XfcePanelPluginFunc) (XfcePanelPlugin *plugin);
const char* xfce_panel_plugin_get_name (XfcePanelPlugin *plugin);
const char* xfce_panel_plugin_get_id (XfcePanelPlugin *plugin);
const char* xfce_panel_plugin_get_display_name
(XfcePanelPlugin *plugin);
int xfce_panel_plugin_get_size (XfcePanelPlugin *plugin);
XfceScreenPosition xfce_panel_plugin_get_screen_position
(XfcePanelPlugin *plugin);
void xfce_panel_plugin_set_expand (XfcePanelPlugin *plugin,
gboolean expand);
gboolean xfce_panel_plugin_get_expand (XfcePanelPlugin *plugin);
GtkOrientation xfce_panel_plugin_get_orientation
(XfcePanelPlugin *plugin);
void xfce_panel_plugin_add_action_widget
(XfcePanelPlugin *plugin,
GtkWidget *widget);
void xfce_panel_plugin_menu_insert_item
(XfcePanelPlugin *plugin,
GtkMenuItem *item);
void xfce_panel_plugin_menu_show_about
(XfcePanelPlugin *plugin);
void xfce_panel_plugin_menu_show_configure
(XfcePanelPlugin *plugin);
void xfce_panel_plugin_block_menu (XfcePanelPlugin *plugin);
void xfce_panel_plugin_unblock_menu (XfcePanelPlugin *plugin);
void xfce_panel_plugin_register_menu (XfcePanelPlugin *plugin,
GtkMenu *menu);
char* xfce_panel_plugin_lookup_rc_file
(XfcePanelPlugin *plugin);
char* xfce_panel_plugin_save_location (XfcePanelPlugin *plugin,
gboolean create);

This shows the prototypes and casts and all that great mumbo-jumbo that you find in most programming reference manuals. This is pure gibberish to me. Not the specific XfcePanelPlugin content but the whole method of describing it that's used in every manual for every function in every language I've ever dealt with.

Maybe it's due to the fact that I have no formal education in programming (or anything else, for that matter as my career in Higher Education was less than stellar {20 credits accumulated in three semesters}). However, give me some example code and at least a verbal description of what it's supposed to do and I'm fine. It is also why I have so much trouble learning C/C++ and similar languages. I learned COBOL in a few weeks; shell in slightly less time; awk in two days; perl... well, no one really learns perl, you just get familiar enough with it to cause all kinds of damage.

I have learned and forgotten other similar languages over the years but I know that, given a little time, I can ramp myself back up in them just fine.

It reminds me of my old Fidonet days. When I was first looking to join I had to install a front end. The two major choices were FrontDoor and BinkleyTerm. FrontDoor was configured by a config program that used the familiar method of screens with text entry lines. Binkley was configured by one big config file with many examples in it. Needless to say I chose Binkley.

Anyway, the point is that, for me, the standard method of describing things for programming doesn't work. I believe I'm not the only one who finds this true. But I bet that most real hackers don't. Which is why this form of documentation endures.

No comments:

Post a Comment