[Geany-devel] Ideas on increasing quality of plugins

Matthew Brush matthewbrush at xxxxx
Fri Mar 11 23:36:50 UTC 2011

On 03/11/11 14:43, Frank Lanitz wrote:
> On Wed, 09 Mar 2011 07:27:06 -0800
> Matthew Brush<matthewbrush at gmail.com>  wrote:
>> On 03/09/11 03:42, Frank Lanitz wrote:
>>> Hi,
>>> Am 23.02.2011 01:10, schrieb Matthew Brush:
>>>> Another thing could be to make mandatory that documentation is
>>>> existent and current, up to some standard.  I mean for README,
>>>> manual, and also doc-comments in code (ex. each function/global
>>>> must have a comment or something).  Some other items where
>>>> documentation could be enforced; new keybindings, preferences,
>>>> menu/toolbar items, tabs.
>>> I agree in a general view. According to code comments I'm not sure.
>>> But can you give me some more details what did you think about when
>>> you referred to the keybindings, preferences etc.?
>> Sure!  The perfect example, although I haven't tried it in a little
>> bit, is the Debugger plugin.  You load the plugin and see the tab in
>> the Message Window, and it looks really cool and useful.  Obviously I
>> wanted to try it out right away, so I start to hover over the GUI
>> elements hoping for some tooltips to guide me to what to do, but
>> nope.  There was nothing in the README (at least when I tried).  So
>> then I tried to just figure it out.  Finally after about 10 minutes I
>> figure out that "Target" means the binary executable you want to
>> debug, which seems kinda obvious now, but at the time the wording
>> alone of "target" didn't seem to cut it.
>> So after that now I want to run it.  I spent another 10-15 minutes
>> looking through the Toolbar, Build menu, Tools menu, etc looking for
>> where I can invoke the Debugger.  There was nothing in the README.
>> Finally I looked under the Keybindings preferences and saw there was
>> keybindings to run it, and there was no default keybindings selected.
>> Point of that story is that *all* I needed was a few hints about what
>> the plugin added to the GUI and what I needed to do to invoke it.
>> Things like the new keybindings, their defaults, etc.  Personally,
>> after using some other IDEs, I would have expect a toolbar menu
>> button with "step into", "step out of", etc.  So I guess what I mean
>> is, if you add a keybinding, or a preference, or a menu item or
>> toolbar item, it should be documented.
>> I don't mean to pick on the Debugger plugin, I think it's *really*
>> cool and I can appreciate that it's still under development, but this
>> is specifically what I was thinking of when I wrote that in my
>> previous message.
> Ah I see. So basicly what you refer to is having a suitable
> documentation at all with most important things as well as ensure there
> is a basic 'ingame' docu. Did I understand it correct?
I'm not sure what "'ingame' docu" means but what I mean is there should 
be a few minimal requirements, such as:
   - Tooltips on widgets added to the UI (where it makes sense)
   - A plugin_help() implementation, even if it just links to the README 
on plugins.geany.org
   - A README file with text content including
       - The purpose of the plugin, what it accomplishes, etc.
       - A list of keybindings that will be available when the plugin is 
       - A usage section explaining at least the basic way to use the plugin
       - A description of the new menu items, tool items, and so on 
introduced to the UI.

This is just some ideas...

Matthew Brush (codebrainz)

More information about the Devel mailing list